-
-
Notifications
You must be signed in to change notification settings - Fork 39
/
files.texi
1999 lines (1724 loc) · 87.6 KB
/
files.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Files, Buffers, Keyboard Macros, Top
@chapter File Handling
@cindex files
The operating system stores data permanently in named @dfn{files}, so
most of the text you edit with Emacs comes from a file and is ultimately
stored in a file.
To edit a file, you must tell Emacs to read the file and prepare a
buffer containing a copy of the file's text. This is called
@dfn{visiting} the file. Editing commands apply directly to text in the
buffer; that is, to the copy inside Emacs. Your changes appear in the
file itself only when you @dfn{save} the buffer back into the file.
In addition to visiting and saving files, Emacs can delete, copy,
rename, and append to files, keep multiple versions of them, and operate
on file directories.
@menu
* File Names:: How to type and edit file-name arguments.
* Visiting:: Visiting a file prepares Emacs to edit the file.
* Saving:: Saving makes your changes permanent.
* Reverting:: Reverting cancels all the changes not saved.
@ifnottex
* Autorevert:: Auto Reverting non-file buffers.
@end ifnottex
* Auto Save:: Auto Save periodically protects against loss of data.
* File Aliases:: Handling multiple names for one file.
* Directories:: Creating, deleting, and listing file directories.
* Comparing Files:: Finding where two files differ.
* Diff Mode:: Mode for editing file differences.
* Misc File Ops:: Other things you can do on files.
* Compressed Files:: Accessing compressed files.
* File Archives:: Operating on tar, zip, jar etc. archive files.
* Remote Files:: Accessing files on other sites.
* Quoted File Names:: Quoting special characters in file names.
* File Name Cache:: Completion against a list of files you often use.
* File Conveniences:: Convenience Features for Finding Files.
* Filesets:: Handling sets of files.
@end menu
@node File Names
@section File Names
@cindex file names
Many Emacs commands that operate on a file require you to specify
the file name, using the minibuffer (@pxref{Minibuffer}). You can use
@dfn{completion} to specify long file names (@pxref{Completion}).
Note that file name completion ignores file names whose extensions
appear in the variable @code{completion-ignored-extensions}
(@pxref{Completion Options}).
For most operations, there is a @dfn{default file name} which is
used if you type just @key{RET} to enter an empty argument. Normally,
the default file name is the name of the file visited in the current
buffer.
@vindex default-directory
@vindex insert-default-directory
Each buffer has a @dfn{default directory} which is normally the same
as the directory of the file visited in that buffer. For example, if
the default file name is @file{/u/rms/gnu/gnu.tasks}, the default
directory is normally @file{/u/rms/gnu/}. The default directory is
kept in the variable @code{default-directory}, which has a separate
value in every buffer. When a command reads a file name using the
minibuffer, the default directory usually serves as the initial
contents of the minibuffer. To inhibit the insertion of the default
directory, set the variable @code{insert-default-directory} to
@code{nil}.
If you enter a file name without a directory, that specifies a file
in the default directory. If you specify a directory in a relative
fashion, with a name that does not start with a slash, it is
interpreted with respect to the default directory. For example,
suppose the default directory is @file{/u/rms/gnu/}. Entering just
@samp{foo} in the minibuffer, with a directory omitted, specifies the
file @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies
@file{/u/rms/.login}; and entering @samp{new/foo} specifies
@file{/u/rms/gnu/new/foo}.
When typing a file name into the minibuffer, you can make use of a
couple of shortcuts: a double slash is interpreted as ``ignore
everything before the second slash in the pair,'' and @samp{~/} is
interpreted as your home directory. @xref{Minibuffer File}, for more
information about these shortcuts.
@findex cd
@findex pwd
The command @kbd{M-x pwd} displays the default directory, and the
command @kbd{M-x cd} sets it to a value read using the minibuffer. A
buffer's default directory changes only when the @code{cd} command is
used. A file-visiting buffer's default directory is initialized to
the directory of the file it visits. If you create a buffer with
@kbd{C-x b}, its default directory is copied from that of the buffer
that was current at the time (@pxref{Select Buffer}).
@cindex environment variables in file names
@cindex expansion of environment variables
@cindex @code{$} in file names
@anchor{File Names with $}The character @samp{$} is used to
substitute an environment variable into a file name. The name of the
environment variable consists of all the alphanumeric characters after
the @samp{$}; alternatively, it can be enclosed in braces after the
@samp{$}. For example, if you have used the shell command
@command{export FOO=rms/hacks} to set up an environment variable named
@env{FOO}, then both @file{/u/$FOO/test.c} and
@file{/u/$@{FOO@}/test.c} are abbreviations for
@file{/u/rms/hacks/test.c}. If the environment variable is not
defined, no substitution occurs, so that the character @samp{$} stands
for itself.
Note that environment variables affect Emacs only if they are
applied before Emacs is started.
To access a file with @samp{$} in its name, if the @samp{$} causes
expansion, type @samp{$$}. This pair is converted to a single
@samp{$} at the same time that variable substitution is performed for
a single @samp{$}. Alternatively, quote the whole file name with
@samp{/:} (@pxref{Quoted File Names}). File names which begin with a
literal @samp{~} should also be quoted with @samp{/:}.
You can include non-@acronym{ASCII} characters in file names if you set the
variable @code{file-name-coding-system} to a non-@code{nil} value.
@xref{File Name Coding}.
@node Visiting
@section Visiting Files
@cindex visiting files
@cindex open file
@table @kbd
@item C-x C-f
Visit a file (@code{find-file}).
@item C-x C-r
Visit a file for viewing, without allowing changes to it
(@code{find-file-read-only}).
@item C-x C-v
Visit a different file instead of the one visited last
(@code{find-alternate-file}).
@item C-x 4 f
Visit a file, in another window (@code{find-file-other-window}). Don't
alter what is displayed in the selected window.
@item C-x 5 f
Visit a file, in a new frame (@code{find-file-other-frame}). Don't
alter what is displayed in the selected frame.
@item M-x find-file-literally
Visit a file with no conversion of the contents.
@end table
@cindex files, visiting and saving
@cindex saving files
@dfn{Visiting} a file means reading its contents into an Emacs
buffer so you can edit them. Emacs makes a new buffer for each file
that you visit.
Emacs normally constructs the buffer name from the file name,
omitting the directory name. For example, a file named
@file{/usr/rms/emacs.tex} is visited in a buffer named
@samp{emacs.tex}. If there is already a buffer with that name, Emacs
constructs a unique name; the normal method is to append @samp{<2>},
@samp{<3>}, and so on, but you can select other methods.
@xref{Uniquify}.
Each window's mode line shows the name of the buffer that is being
displayed in that window, so you can always tell what buffer you are
editing. @pxref{Mode Line}.
The changes you make with editing commands are made in the Emacs
buffer. They do not take effect in the file that you visited, or any
permanent place, until you @dfn{save} the buffer (@pxref{Saving}).
@cindex modified (buffer)
If a buffer contains changes that have not been saved, we say the
buffer is @dfn{modified}. This implies that some changes will be lost
if the buffer is not saved. The mode line displays two stars near the
left margin to indicate that the buffer is modified.
@kindex C-x C-f
@findex find-file
To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the
minibuffer to enter the name of the desired file. The usual
defaulting and completion behavior is available in this minibuffer
(@pxref{Minibuffer File}). Note, also, that completion ignores
certain file names (@pxref{Completion Options}). While in the
minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
Your can tell that @kbd{C-x C-f} has completed successfully by the
appearance of new text on the screen and a new buffer name in the mode
line. If the specified file does not exist and you could not create
it, or exists but you can't read it, an error message is displayed in
the echo area.
If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
another copy. It selects the existing buffer containing that file.
However, before doing so, it checks whether the file itself has changed
since you visited or saved it last. If the file has changed, Emacs offers
to reread it.
@vindex large-file-warning-threshold
@cindex maximum buffer size exceeded, error message
If you try to visit a file larger than
@code{large-file-warning-threshold} (the default is 10000000, which is
about 10 megabytes), Emacs asks you for confirmation first. You can
answer @kbd{y} to proceed with visiting the file. Note, however, that
Emacs cannot visit files that are larger than the maximum Emacs buffer
size, which is around 512 megabytes on 32-bit machines
(@pxref{Buffers}). If you try, Emacs will display an error message
saying that the maximum buffer size has been exceeded.
@cindex wildcard characters in file names
@vindex find-file-wildcards
If the file name you specify contains shell-style wildcard
characters, Emacs visits all the files that match it. (On
case-insensitive filesystems, Emacs matches the wildcards disregarding
the letter case.) Wildcards include @samp{?}, @samp{*}, and
@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file
name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted
File Names}, for information on how to visit a file whose name
actually contains wildcard characters. You can disable the wildcard
feature by customizing @code{find-file-wildcards}.
@cindex file selection dialog
On graphical displays, there are two additional methods for visiting
files. Firstly, when Emacs is built with a suitable GUI toolkit,
commands invoked with the mouse (by clicking on the menu bar or tool
bar) use the toolkit's standard ``File Selection'' dialog instead of
prompting for the file name in the minibuffer. On GNU/Linux and Unix
platforms, Emacs does this when built with GTK, LessTif, and Motif
toolkits; on MS-Windows and Mac, the GUI version does that by default.
For information on how to customize this, see @ref{Dialog Boxes}.
Secondly, Emacs supports ``drag and drop'': dropping a file into an
ordinary Emacs window visits the file using that window. As an
exception, dropping a file into a window displaying a Dired buffer
moves or copies the file into the displayed directory. For details,
see @ref{Drag and Drop}, and @ref{Misc Dired Features}.
@cindex creating files
What if you want to create a new file? Just visit it. Emacs
displays @samp{(New file)} in the echo area, but in other respects
behaves as if you had visited an existing empty file. If you make
changes and save them, the file is created.
@cindex minibuffer confirmation
@cindex confirming in the minibuffer
@vindex confirm-nonexistent-file-or-buffer
When @key{TAB} completion results in a nonexistent file name and you
type @key{RET} immediately to visit it, Emacs asks for confirmation;
this is because it's possible that you expected completion to go
further and give you an existing file's name. The string
@samp{[Confirm]} appears for a short time after the file name to
indicate the need to confirm in this way. Type @key{RET} to confirm
and visit the nonexistent file. The variable
@code{confirm-nonexistent-file-or-buffer} controls whether Emacs asks
for confirmation before visiting a new file. The default value,
@code{after-completion}, gives the behavior we have just described.
If the value is @code{nil}, Emacs never asks for confirmation; for any
other non-@code{nil} value, Emacs always asks for confirmation. This
variable also affects the @code{switch-to-buffer} command
(@pxref{Select Buffer}). @xref{Completion}, for more information
about completion.
@kindex C-x C-v
@findex find-alternate-file
If you visit a nonexistent file unintentionally (because you typed
the wrong file name), type @kbd{C-x C-v} (@code{find-alternate-file})
to visit the file you really wanted. @kbd{C-x C-v} is similar to
@kbd{C-x C-f}, but it kills the current buffer (after first offering
to save it if it is modified). When @kbd{C-x C-v} reads the file name
to visit, it inserts the entire default file name in the buffer, with
point just after the directory part; this is convenient if you made a
slight error in typing the name.
@vindex find-file-run-dired
If you ``visit'' a file that is actually a directory, Emacs invokes
Dired, the Emacs directory browser; this lets you ``edit'' the
contents of the directory. @xref{Dired}. You can disable this
behavior by setting the variable @code{find-file-run-dired} to
@code{nil}; in that case, it is an error to try to visit a directory.
Files which are actually collections of other files, or @dfn{file
archives}, are visited in special modes which invoke a Dired-like
environment to allow operations on archive members. @xref{File
Archives}, for more about these features.
If you visit a file that the operating system won't let you modify,
or that is marked read-only, Emacs makes the buffer read-only too, so
that you won't go ahead and make changes that you'll have trouble
saving afterward. You can make the buffer writable with @kbd{C-x C-q}
(@code{toggle-read-only}). @xref{Misc Buffer}.
@kindex C-x C-r
@findex find-file-read-only
If you want to visit a file as read-only in order to protect
yourself from entering changes accidentally, visit it with the command
@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
@kindex C-x 4 f
@findex find-file-other-window
@kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
except that the buffer containing the specified file is selected in another
window. The window that was selected before @kbd{C-x 4 f} continues to
show the same buffer it was already showing. If this command is used when
only one window is being displayed, that window is split in two, with one
window showing the same buffer as before, and the other one showing the
newly requested file. @xref{Windows}.
@kindex C-x 5 f
@findex find-file-other-frame
@kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
new frame, or makes visible any existing frame showing the file you
seek. This feature is available only when you are using a window
system. @xref{Frames}.
Emacs recognizes from the contents of a file which end-of-line
convention it uses to separate lines---newline (used on GNU/Linux and
on Unix), carriage-return linefeed (used on Microsoft systems), or
just carriage-return (used on the Macintosh)---and automatically
converts the contents to the normal Emacs convention, which is that
the newline character separates lines. This is a part of the general
feature of coding system conversion (@pxref{Coding Systems}), and
makes it possible to edit files imported from different operating
systems with equal convenience. If you change the text and save the
file, Emacs performs the inverse conversion, changing newlines back
into carriage-return linefeed or just carriage-return if appropriate.
@findex find-file-literally
If you wish to edit a file as a sequence of @acronym{ASCII}
characters with no special encoding or conversion, use the @kbd{M-x
find-file-literally} command. This visits a file, like @kbd{C-x C-f},
but does not do format conversion (@pxref{Formatted Text}), character
code conversion (@pxref{Coding Systems}), or automatic uncompression
(@pxref{Compressed Files}), and does not add a final newline because
of @code{require-final-newline} (@pxref{Customize Save}). If you have
already visited the same file in the usual (non-literal) manner, this
command asks you whether to visit it literally instead.
@vindex find-file-hook
@vindex find-file-not-found-functions
Two special hook variables allow extensions to modify the operation of
visiting files. Visiting a file that does not exist runs the functions
in the list @code{find-file-not-found-functions}; this variable holds a list
of functions, and the functions are called one by one (with no
arguments) until one of them returns non-@code{nil}. This is not a
normal hook, and the name ends in @samp{-functions} rather than @samp{-hook}
to indicate that fact.
Successful visiting of any file, whether existing or not, calls the
functions in the list @code{find-file-hook}, with no arguments.
This variable is a normal hook. In the case of a nonexistent file, the
@code{find-file-not-found-functions} are run first. @xref{Hooks}.
There are several ways to specify automatically the major mode for
editing the file (@pxref{Choosing Modes}), and to specify local
variables defined for that file (@pxref{File Variables}).
@node Saving
@section Saving Files
@dfn{Saving} a buffer in Emacs means writing its contents back into the file
that was visited in the buffer.
@menu
* Save Commands:: Commands for saving files.
* Backup:: How Emacs saves the old version of your file.
* Customize Save:: Customizing the saving of files.
* Interlocking:: How Emacs protects against simultaneous editing
of one file by two users.
* Shadowing: File Shadowing. Copying files to "shadows" automatically.
* Time Stamps:: Emacs can update time stamps on saved files.
@end menu
@node Save Commands
@subsection Commands for Saving Files
These are the commands that relate to saving and writing files.
@table @kbd
@item C-x C-s
Save the current buffer in its visited file on disk (@code{save-buffer}).
@item C-x s
Save any or all buffers in their visited files (@code{save-some-buffers}).
@item M-~
Forget that the current buffer has been changed (@code{not-modified}).
With prefix argument (@kbd{C-u}), mark the current buffer as changed.
@item C-x C-w
Save the current buffer with a specified file name (@code{write-file}).
@item M-x set-visited-file-name
Change the file name under which the current buffer will be saved.
@end table
@kindex C-x C-s
@findex save-buffer
When you wish to save the file and make your changes permanent, type
@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
displays a message like this:
@example
Wrote /u/rms/gnu/gnu.tasks
@end example
@noindent
If the selected buffer is not modified (no changes have been made in it
since the buffer was created or last saved), saving is not really done,
because it would have no effect. Instead, @kbd{C-x C-s} displays a message
like this in the echo area:
@example
(No changes need to be saved)
@end example
With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer
to be backed up when the next save is done. @xref{Backup}.
@kindex C-x s
@findex save-some-buffers
The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
or all modified buffers. It asks you what to do with each buffer. The
possible responses are analogous to those of @code{query-replace}:
@table @kbd
@item y
Save this buffer and ask about the rest of the buffers.
@item n
Don't save this buffer, but ask about the rest of the buffers.
@item !
Save this buffer and all the rest with no more questions.
@c following generates acceptable underfull hbox
@item @key{RET}
Terminate @code{save-some-buffers} without any more saving.
@item .
Save this buffer, then exit @code{save-some-buffers} without even asking
about other buffers.
@item C-r
View the buffer that you are currently being asked about. When you exit
View mode, you get back to @code{save-some-buffers}, which asks the
question again.
@item d
Diff the buffer against its corresponding file, so you can see what
changes you would be saving. This calls the command
@code{diff-buffer-with-file} (@pxref{Comparing Files}).
@item C-h
Display a help message about these options.
@end table
@kbd{C-x C-c}, the key sequence to exit Emacs, invokes
@code{save-some-buffers} and therefore asks the same questions.
@kindex M-~
@findex not-modified
If you have changed a buffer but do not wish to save the changes,
you should take some action to prevent it. Otherwise, each time you
use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer
by mistake. One thing you can do is type @kbd{M-~}
(@code{not-modified}), which clears out the indication that the buffer
is modified. If you do this, none of the save commands will believe
that the buffer needs to be saved. (@samp{~} is often used as a
mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.)
Alternatively, you can cancel all the changes made since the file was
visited or saved, by reading the text from the file again. This is
called @dfn{reverting}. @xref{Reverting}. (You could also undo all
the changes by repeating the undo command @kbd{C-x u} until you have
undone all the changes; but reverting is easier.)
@findex set-visited-file-name
@kbd{M-x set-visited-file-name} alters the name of the file that the
current buffer is visiting. It reads the new file name using the
minibuffer. Then it marks the buffer as visiting that file name, and
changes the buffer name correspondingly. @code{set-visited-file-name}
does not save the buffer in the newly visited file; it just alters the
records inside Emacs in case you do save later. It also marks the
buffer as ``modified'' so that @kbd{C-x C-s} in that buffer
@emph{will} save.
@kindex C-x C-w
@findex write-file
If you wish to mark the buffer as visiting a different file and save
it right away, use @kbd{C-x C-w} (@code{write-file}). This is
equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s},
except that @kbd{C-x C-w} asks for confirmation if the file exists.
@kbd{C-x C-s} used on a buffer that is not visiting a file has the
same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
buffer as visiting that file, and saves it there. The default file
name in a buffer that is not visiting a file is made by combining the
buffer name with the buffer's default directory (@pxref{File Names}).
If the new file name implies a major mode, then @kbd{C-x C-w} switches
to that major mode, in most cases. The command
@code{set-visited-file-name} also does this. @xref{Choosing Modes}.
If Emacs is about to save a file and sees that the date of the latest
version on disk does not match what Emacs last read or wrote, Emacs
notifies you of this fact, because it probably indicates a problem caused
by simultaneous editing and requires your immediate attention.
@xref{Interlocking,, Simultaneous Editing}.
@node Backup
@subsection Backup Files
@cindex backup file
@vindex make-backup-files
@vindex vc-make-backup-files
On most operating systems, rewriting a file automatically destroys all
record of what the file used to contain. Thus, saving a file from Emacs
throws away the old contents of the file---or it would, except that
Emacs carefully copies the old contents to another file, called the
@dfn{backup} file, before actually saving.
Emacs makes a backup for a file only the first time the file is
saved from a buffer. No matter how many times you subsequently save
the file, its backup remains unchanged. However, if you kill the
buffer and then visit the file again, a new backup file will be made.
For most files, the variable @code{make-backup-files} determines
whether to make backup files. On most operating systems, its default
value is @code{t}, so that Emacs does write backup files.
For files managed by a version control system (@pxref{Version
Control}), the variable @code{vc-make-backup-files} determines whether
to make backup files. By default it is @code{nil}, since backup files
are redundant when you store all the previous versions in a version
control system.
@iftex
@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}.
@end iftex
@ifnottex
@xref{General VC Options}.
@end ifnottex
At your option, Emacs can keep either a single backup for each file,
or make a series of numbered backup files for each file that you edit.
@xref{Backup Names}.
@vindex backup-enable-predicate
@vindex temporary-file-directory
@vindex small-temporary-file-directory
The default value of the @code{backup-enable-predicate} variable
prevents backup files being written for files in the directories used
for temporary files, specified by @code{temporary-file-directory} or
@code{small-temporary-file-directory}.
You can explicitly tell Emacs to make another backup file from a
buffer, even though that buffer has been saved before. If you save
the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
into a backup file if you save the buffer again. @kbd{C-u C-u C-x
C-s} saves the buffer, but first makes the previous file contents into
a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it
makes a backup from the previous contents, and arranges to make
another from the newly saved contents if you save again.
@menu
* Names: Backup Names. How backup files are named.
* Deletion: Backup Deletion. Emacs deletes excess numbered backups.
* Copying: Backup Copying. Backups can be made by copying or renaming.
@end menu
@node Backup Names
@subsubsection Single or Numbered Backups
When Emacs makes a backup file, its name is normally constructed by
appending @samp{~} to the file name being edited; thus, the backup
file for @file{eval.c} would be @file{eval.c~}.
If access control stops Emacs from writing backup files under the
usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}.
Only one such file can exist, so only the most recently made such
backup is available.
Emacs can also make @dfn{numbered backup files}. Numbered backup
file names contain @samp{.~}, the number, and another @samp{~} after
the original file name. Thus, the backup files of @file{eval.c} would
be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way
through names like @file{eval.c.~259~} and beyond.
@vindex version-control
The variable @code{version-control} determines whether to make
single backup files or multiple numbered backup files. Its possible
values are:
@table @code
@item nil
Make numbered backups for files that have numbered backups already.
Otherwise, make single backups. This is the default.
@item t
Make numbered backups.
@item never
Never make numbered backups; always make single backups.
@end table
@noindent
The usual way to set this variable is globally, through your
@file{.emacs} file or the customization buffer. However, you can set
@code{version-control} locally in an individual buffer to control the
making of backups for that buffer's file (@pxref{Locals}). You can
have Emacs set @code{version-control} locally whenever you visit a
given file (@pxref{File Variables}). Some modes, such as Rmail mode,
set this variable.
@cindex @env{VERSION_CONTROL} environment variable
If you set the environment variable @env{VERSION_CONTROL}, to tell
various GNU utilities what to do with backup files, Emacs also obeys the
environment variable by setting the Lisp variable @code{version-control}
accordingly at startup. If the environment variable's value is @samp{t}
or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
value is @samp{nil} or @samp{existing}, then @code{version-control}
becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
@code{version-control} becomes @code{never}.
@vindex backup-directory-alist
You can customize the variable @code{backup-directory-alist} to
specify that files matching certain patterns should be backed up in
specific directories. This variable applies to both single and
numbered backups. A typical use is to add an element @code{("."
. @var{dir})} to make all backups in the directory with absolute name
@var{dir}; Emacs modifies the backup file names to avoid clashes
between files with the same names originating in different
directories. Alternatively, adding, @code{("." . ".~")} would make
backups in the invisible subdirectory @file{.~} of the original file's
directory. Emacs creates the directory, if necessary, to make the
backup.
@vindex make-backup-file-name-function
If you define the variable @code{make-backup-file-name-function} to
a suitable Lisp function, that overrides the usual way Emacs
constructs backup file names.
@node Backup Deletion
@subsubsection Automatic Deletion of Backups
To prevent excessive consumption of disk space, Emacs can delete numbered
backup versions automatically. Generally Emacs keeps the first few backups
and the latest few backups, deleting any in between. This happens every
time a new backup is made.
@vindex kept-old-versions
@vindex kept-new-versions
The two variables @code{kept-old-versions} and
@code{kept-new-versions} control this deletion. Their values are,
respectively, the number of oldest (lowest-numbered) backups to keep
and the number of newest (highest-numbered) ones to keep, each time a
new backup is made. The backups in the middle (excluding those oldest
and newest) are the excess middle versions---those backups are
deleted. These variables' values are used when it is time to delete
excess versions, just after a new backup version is made; the newly
made backup is included in the count in @code{kept-new-versions}. By
default, both variables are 2.
@vindex delete-old-versions
If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
backup files silently. If it is @code{nil}, the default, Emacs asks
you whether it should delete the excess backup versions. If it has
any other value, then Emacs never automatically deletes backups.
Dired's @kbd{.} (Period) command can also be used to delete old versions.
@xref{Dired Deletion}.
@node Backup Copying
@subsubsection Copying vs.@: Renaming
Backup files can be made by copying the old file or by renaming it.
This makes a difference when the old file has multiple names (hard
links). If the old file is renamed into the backup file, then the
alternate names become names for the backup file. If the old file is
copied instead, then the alternate names remain names for the file
that you are editing, and the contents accessed by those names will be
the new contents.
The method of making a backup file may also affect the file's owner
and group. If copying is used, these do not change. If renaming is used,
you become the file's owner, and the file's group becomes the default
(different operating systems have different defaults for the group).
Having the owner change is usually a good idea, because then the owner
always shows who last edited the file. Also, the owners of the backups
show who produced those versions. Occasionally there is a file whose
owner should not change; it is a good idea for such files to contain
local variable lists to set @code{backup-by-copying-when-mismatch}
locally (@pxref{File Variables}).
@vindex backup-by-copying
@vindex backup-by-copying-when-linked
@vindex backup-by-copying-when-mismatch
@vindex backup-by-copying-when-privileged-mismatch
@cindex file ownership, and backup
@cindex backup, and user-id
The choice of renaming or copying is controlled by four variables.
Renaming is the default choice. If the variable
@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise,
if the variable @code{backup-by-copying-when-linked} is non-@code{nil},
then copying is used for files that have multiple names, but renaming
may still be used when the file being edited has only one name. If the
variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then
copying is used if renaming would cause the file's owner or group to
change. @code{backup-by-copying-when-mismatch} is @code{t} by default
if you start Emacs as the superuser. The fourth variable,
@code{backup-by-copying-when-privileged-mismatch}, gives the highest
numeric user-id for which @code{backup-by-copying-when-mismatch} will be
forced on. This is useful when low-numbered user-ids are assigned to
special system users, such as @code{root}, @code{bin}, @code{daemon},
etc., which must maintain ownership of files.
When a file is managed with a version control system (@pxref{Version
Control}), Emacs does not normally make backups in the usual way for
that file. But check-in and check-out are similar in some ways to
making backups. One unfortunate similarity is that these operations
typically break hard links, disconnecting the file name you visited from
any alternate names for the same file. This has nothing to do with
Emacs---the version control system does it.
@node Customize Save
@subsection Customizing Saving of Files
@vindex require-final-newline
If the value of the variable @code{require-final-newline} is
@code{t}, saving or writing a file silently puts a newline at the end
if there isn't already one there. If the value is @code{visit}, Emacs
adds a newline at the end of any file that doesn't have one, just
after it visits the file. (This marks the buffer as modified, and you
can undo it.) If the value is @code{visit-save}, that means to add
newlines both on visiting and on saving. If the value is @code{nil},
Emacs leaves the end of the file unchanged; if it's neither @code{nil}
nor @code{t}, Emacs asks you whether to add a newline. The default is
@code{nil}.
@vindex mode-require-final-newline
Many major modes are designed for specific kinds of files that are
always supposed to end in newlines. These major modes set the
variable @code{require-final-newline} according to
@code{mode-require-final-newline}. By setting the latter variable,
you can control how these modes handle final newlines.
@vindex write-region-inhibit-fsync
When Emacs saves a file, it invokes the @code{fsync} system call to
force the data immediately out to disk. This is important for safety
if the system crashes or in case of power outage. However, it can be
disruptive on laptops using power saving, because it requires the disk
to spin up each time you save a file. Setting
@code{write-region-inhibit-fsync} to a non-@code{nil} value disables
this synchronization. Be careful---this means increased risk of data
loss.
@node Interlocking
@subsection Protection against Simultaneous Editing
@cindex file dates
@cindex simultaneous editing
Simultaneous editing occurs when two users visit the same file, both
make changes, and then both save them. If nobody were informed that
this was happening, whichever user saved first would later find that his
changes were lost.
On some systems, Emacs notices immediately when the second user starts
to change the file, and issues an immediate warning. On all systems,
Emacs checks when you save the file, and warns if you are about to
overwrite another user's changes. You can prevent loss of the other
user's work by taking the proper corrective action instead of saving the
file.
@findex ask-user-about-lock
@cindex locking files
When you make the first modification in an Emacs buffer that is
visiting a file, Emacs records that the file is @dfn{locked} by you.
(It does this by creating a specially-named symbolic link in the same
directory.) Emacs removes the lock when you save the changes. The
idea is that the file is locked whenever an Emacs buffer visiting it
has unsaved changes.
@cindex collision
If you begin to modify the buffer while the visited file is locked by
someone else, this constitutes a @dfn{collision}. When Emacs detects a
collision, it asks you what to do, by calling the Lisp function
@code{ask-user-about-lock}. You can redefine this function for the sake
of customization. The standard definition of this function asks you a
question and accepts three possible answers:
@table @kbd
@item s
Steal the lock. Whoever was already changing the file loses the lock,
and you gain the lock.
@item p
Proceed. Go ahead and edit the file despite its being locked by someone else.
@item q
Quit. This causes an error (@code{file-locked}), and the buffer
contents remain unchanged---the modification you were trying to make
does not actually take place.
@end table
Note that locking works on the basis of a file name; if a file has
multiple names, Emacs does not realize that the two names are the same file
and cannot prevent two users from editing it simultaneously under different
names. However, basing locking on names means that Emacs can interlock the
editing of new files that will not really exist until they are saved.
Some systems are not configured to allow Emacs to make locks, and
there are cases where lock files cannot be written. In these cases,
Emacs cannot detect trouble in advance, but it still can detect the
collision when you try to save a file and overwrite someone else's
changes. Every time Emacs saves a buffer, it first checks the
last-modification date of the existing file on disk to verify that it
has not changed since the file was last visited or saved. If the date
does not match, it implies that changes were made in the file in some
other way, and these changes are about to be lost if Emacs actually
does save. To prevent this, Emacs displays a warning message and asks
for confirmation before saving. Occasionally you will know why the
file was changed and know that it does not matter; then you can answer
@kbd{yes} and proceed. Otherwise, you should cancel the save with
@kbd{C-g} and investigate the situation.
If Emacs or the operating system crashes, this may leave behind lock
files which are stale, so you may occasionally get warnings about
spurious collisions. When you determine that the collision is spurious,
just use @kbd{p} to tell Emacs to go ahead anyway.
The first thing you should do when notified that simultaneous editing
has already taken place is to list the directory with @kbd{C-u C-x C-d}
(@pxref{Directories}). This shows the file's current author. You
should attempt to contact him to warn him not to continue editing.
Often the next step is to save the contents of your Emacs buffer under a
different name, and use @code{diff} to compare the two files.@refill
@node File Shadowing
@subsection Shadowing Files
@cindex shadow files
@cindex file shadows
@findex shadow-initialize
@table @kbd
@item M-x shadow-initialize
Set up file shadowing.
@item M-x shadow-define-literal-group
Declare a single file to be shared between sites.
@item M-x shadow-define-regexp-group
Make all files that match each of a group of files be shared between hosts.
@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
Define a shadow file cluster @var{name}.
@item M-x shadow-copy-files
Copy all pending shadow files.
@item M-x shadow-cancel
Cancel the instruction to shadow some files.
@end table
You can arrange to keep identical @dfn{shadow} copies of certain files
in more than one place---possibly on different machines. To do this,
first you must set up a @dfn{shadow file group}, which is a set of
identically-named files shared between a list of sites. The file
group is permanent and applies to further Emacs sessions as well as
the current one. Once the group is set up, every time you exit Emacs,
it will copy the file you edited to the other files in its group. You
can also do the copying without exiting Emacs, by typing @kbd{M-x
shadow-copy-files}.
To set up a shadow file group, use @kbd{M-x
shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}.
See their documentation strings for further information.
Before copying a file to its shadows, Emacs asks for confirmation.
You can answer ``no'' to bypass copying of this file, this time. If
you want to cancel the shadowing permanently for a certain file, use
@kbd{M-x shadow-cancel} to eliminate or change the shadow file group.
A @dfn{shadow cluster} is a group of hosts that share directories, so
that copying to or from one of them is sufficient to update the file
on all of them. Each shadow cluster has a name, and specifies the
network address of a primary host (the one we copy files to), and a
regular expression that matches the host names of all the other hosts
in the cluster. You can define a shadow cluster with @kbd{M-x
shadow-define-cluster}.
@node Time Stamps
@subsection Updating Time Stamps Automatically
@cindex time stamps
@cindex modification dates
@cindex locale, date format
You can arrange to put a time stamp in a file, so that it will be updated
automatically each time you edit and save the file. The time stamp
has to be in the first eight lines of the file, and you should
insert it like this:
@example
Time-stamp: <>
@end example
@noindent
or like this:
@example
Time-stamp: " "
@end example
@findex time-stamp
Then add the hook function @code{time-stamp} to the hook
@code{before-save-hook}; that hook function will automatically update
the time stamp, inserting the current date and time when you save the
file. You can also use the command @kbd{M-x time-stamp} to update the
time stamp manually. For other customizations, see the Custom group
@code{time-stamp}. Note that non-numeric fields in the time stamp are
formatted according to your locale setting (@pxref{Environment}).
@node Reverting
@section Reverting a Buffer
@findex revert-buffer
@cindex drastic changes
@cindex reread a file
If you have made extensive changes to a file and then change your mind
about them, you can get rid of them by reading in the previous version
of the file. To do this, use @kbd{M-x revert-buffer}, which operates on
the current buffer. Since reverting a buffer unintentionally could lose
a lot of work, you must confirm this command with @kbd{yes}.
@code{revert-buffer} tries to position point in such a way that, if
the file was edited only slightly, you will be at approximately the
same piece of text after reverting as before. However, if you have made
drastic changes, point may wind up in a totally different piece of text.
Reverting marks the buffer as ``not modified''.
Some kinds of buffers that are not associated with files, such as
Dired buffers, can also be reverted. For them, reverting means
recalculating their contents. Buffers created explicitly with
@kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error
if you try.
@vindex revert-without-query
When you edit a file that changes automatically and frequently---for
example, a log of output from a process that continues to run---it may
be useful for Emacs to revert the file without querying you. To
request this behavior, set the variable @code{revert-without-query} to
a list of regular expressions. When a file name matches one of these
regular expressions, @code{find-file} and @code{revert-buffer} will
revert it automatically if it has changed---provided the buffer itself
is not modified. (If you have edited the text, it would be wrong to
discard your changes.)
@cindex Global Auto-Revert mode
@cindex mode, Global Auto-Revert
@cindex Auto-Revert mode
@cindex mode, Auto-Revert
@findex global-auto-revert-mode
@findex auto-revert-mode
@findex auto-revert-tail-mode
@vindex auto-revert-interval
In addition, you can tell Emacs to periodically revert a buffer by
typing @kbd{M-x auto-revert-mode}. This turns on Auto-Revert mode, a
minor mode that makes Emacs automatically revert the current buffer
every five seconds. You can change this interval through the variable
@code{auto-revert-interval}. Typing @kbd{M-x global-auto-revert-mode}
enables Global Auto-Revert mode, which does the same for all file
buffers. Auto-Revert mode and Global Auto-Revert modes do not check
or revert remote files, because that is usually too slow.
One use of Auto-Revert mode is to ``tail'' a file such as a system
log, so that changes made to that file by other programs are
continuously displayed. To do this, just move the point to the end of
the buffer, and it will stay there as the file contents change.
However, if you are sure that the file will only change by growing at
the end, use Auto-Revert Tail mode instead
(@code{auto-revert-tail-mode}). It is more efficient for this.
Auto-Revert Tail mode works also for remote files.
@xref{VC Mode Line}, for Auto Revert peculiarities in buffers that
visit files under version control.
@ifnottex
@include arevert-xtra.texi
@end ifnottex
@node Auto Save
@section Auto-Saving: Protection Against Disasters
@cindex Auto Save mode
@cindex mode, Auto Save
@cindex crashes
From time to time, Emacs automatically saves each visited file in a
separate file, without altering the file you actually use. This is
called @dfn{auto-saving}. It prevents you from losing more than a
limited amount of work if the system crashes.
When Emacs determines that it is time for auto-saving, it considers
each buffer, and each is auto-saved if auto-saving is enabled for it
and it has been changed since the last time it was auto-saved. The
message @samp{Auto-saving...} is displayed in the echo area during
auto-saving, if any files are actually auto-saved. Errors occurring
during auto-saving are caught so that they do not interfere with the
execution of commands you have been typing.
@menu
* Files: Auto Save Files. The file where auto-saved changes are
actually made until you save the file.
* Control: Auto Save Control. Controlling when and how often to auto-save.
* Recover:: Recovering text from auto-save files.
@end menu