![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to emacs-5 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / emacs / info|
Return to emacs-5 CVS log | Up to [Apple XNU] / GNUtools / emacs / info |
1.1 root 1: This is Info file ../info/emacs, produced by Makeinfo-1.49 from the
2: input file emacs.texi.
3:
4: This file documents the GNU Emacs editor.
5:
6: Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman.
7:
8: Permission is granted to make and distribute verbatim copies of this
9: manual provided the copyright notice and this permission notice are
10: preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of
13: this manual under the conditions for verbatim copying, provided also
14: that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
15: General Public License" are included exactly as in the original, and
16: provided that the entire resulting derived work is distributed under the
17: terms of a permission notice identical to this one.
18:
19: Permission is granted to copy and distribute translations of this
20: manual into another language, under the above conditions for modified
21: versions, except that the sections entitled "The GNU Manifesto",
22: "Distribution" and "GNU General Public License" may be included in a
23: translation approved by the author instead of in the original English.
24:
25:
26: File: emacs, Node: File Names, Next: Visiting, Prev: Files, Up: Files
27:
28: File Names
29: ==========
30:
31: Most Emacs commands that operate on a file require you to specify the
32: file name. (Saving and reverting are exceptions; the buffer knows which
33: file name to use for them.) File names are specified using the
34: minibuffer (*note Minibuffer::.). "Completion" is available, to make
35: it easier to specify long file names. *Note Completion::.
36:
37: There is always a "default file name" which will be used if you type
38: just RET, entering an empty argument. Normally the default file name
39: is the name of the file visited in the current buffer; this makes it
40: easy to operate on that file with any of the Emacs file commands.
41:
42: Each buffer has a default directory, normally the same as the
43: directory of the file visited in that buffer. When Emacs reads a file
44: name, if you do not specify a directory, the default directory is used.
45: If you specify a directory in a relative fashion, with a name that
46: does not start with a slash, it is interpreted with respect to the
47: default directory. The default directory is kept in the variable
48: `default-directory', which has a separate value in every buffer.
49:
50: For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
51: the default directory is `/u/rms/gnu/'. If you type just `foo', which
52: does not specify a directory, it is short for `/u/rms/gnu/foo'.
53: `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
54: the filename `/u/rms/gnu/new/foo'.
55:
56: The command `M-x pwd' prints the current buffer's default directory,
57: and the command `M-x cd' sets it (to a value read using the
58: minibuffer). A buffer's default directory changes only when the `cd'
59: command is used. A file-visiting buffer's default directory is
60: initialized to the directory of the file that is visited there. If a
61: buffer is made randomly with `C-x b', its default directory is copied
62: from that of the buffer that was current at the time.
63:
64: The default directory actually appears in the minibuffer when the
65: minibuffer becomes active to read a file name. This serves two
66: purposes: it shows you what the default is, so that you can type a
67: relative file name and know with certainty what it will mean, and it
68: allows you to edit the default to specify a different directory. This
69: insertion of the default directory is inhibited if the variable
70: `insert-default-directory' is set to `nil'.
71:
72: Note that it is legitimate to type an absolute file name after you
73: enter the minibuffer, ignoring the presence of the default directory
74: name as part of the text. The final minibuffer contents may look
75: invalid, but that is not so. *Note Minibuffer File::.
76:
77: `$' in a file name is used to substitute environment variables. For
78: example, if you have used the C shell command `setenv FOO rms/hacks' to
79: set up an environment variable named `FOO', then you can use
80: `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
81: `/u/rms/hacks/test.c'. (In the Bourne-Again shell, write `export
82: FOO=rms/hacks' to define `FOO'.) The environment variable name
83: consists of all the alphanumeric characters after the `$';
84: alternatively, it may be enclosed in braces after the `$'. Note that
85: the `setenv' command affects Emacs only if done before Emacs is started.
86:
87: To access a file with `$' in its name, type `$$'. This pair is
88: converted to a single `$' at the same time as variable substitution is
89: performed for single `$'. The Lisp function that performs the
90: substitution is called `substitute-in-file-name'. The substitution is
91: performed only on filenames read as such using the minibuffer.
92:
93:
94: File: emacs, Node: Visiting, Next: Saving, Prev: File Names, Up: Files
95:
96: Visiting Files
97: ==============
98:
99: `C-x C-f'
100: Visit a file (`find-file').
101:
102: `C-x C-v'
103: Visit a different file instead of the one visited last
104: (`find-alternate-file').
105:
106: `C-x 4 C-f'
107: Visit a file, in another window (`find-file-other-window'). Don't
108: change this window.
109:
110: "Visiting" a file means copying its contents into Emacs where you can
111: edit them. Emacs makes a new buffer for each file that you visit. We
112: say that the buffer is visiting the file that it was created to hold.
113: Emacs constructs the buffer name from the file name by throwing away the
114: directory, keeping just the name proper. For example, a file named
115: `/usr/rms/emacs.tex' would get a buffer named `emacs.tex'. If there is
116: already a buffer with that name, a unique name is constructed by
117: appending `<2>', `<3>', or so on, using the lowest number that makes a
118: name that is not already in use.
119:
120: Each window's mode line shows the name of the buffer that is being
121: displayed in that window, so you can always tell what buffer you are
122: editing.
123:
124: The changes you make with Emacs are made in the Emacs buffer. They
125: do not take effect in the file that you visited, or any place
126: permanent, until you "save" the buffer. Saving the buffer means that
127: Emacs writes the current contents of the buffer into its visited file.
128: *Note Saving::.
129:
130: If a buffer contains changes that have not been saved, the buffer is
131: said to be "modified". This is important because it implies that some
132: changes will be lost if the buffer is not saved. The mode line displays
133: two stars near the left margin if the buffer is modified.
134:
135: To visit a file, use the command `C-x C-f' (`find-file'). Follow
136: the command with the name of the file you wish to visit, terminated by a
137: RET.
138:
139: The file name is read using the minibuffer (*note Minibuffer::.),
140: with defaulting and completion in the standard manner (*note File
141: Names::.). While in the minibuffer, you can abort `C-x C-f' by typing
142: `C-g'.
143:
144: Your confirmation that `C-x C-f' has completed successfully is the
145: appearance of new text on the screen and a new buffer name in the mode
146: line. If the specified file does not exist and could not be created, or
147: cannot be read, then an error results. The error message is printed in
148: the echo area, and includes the file name which Emacs was trying to
149: visit.
150:
151: If you visit a file that is already in Emacs, `C-x C-f' does not make
152: another copy. It selects the existing buffer containing that file.
153: However, before doing so, it checks that the file itself has not changed
154: since you visited or saved it last. If the file has changed, a warning
155: message is printed. *Note Simultaneous Editing: Interlocking.
156:
157: What if you want to create a file? Just visit it. Emacs prints
158: `(New File)' in the echo area, but in other respects behaves as if you
159: had visited an existing empty file. If you make any changes and save
160: them, the file is created.
161:
162: If you visit a nonexistent file unintentionally (because you typed
163: the wrong file name), use the `C-x C-v' (`find-alternate-file') command
164: to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but
165: it kills the current buffer (after first offering to save it if it is
166: modified). `C-x C-v' is allowed even if the current buffer is not
167: visiting a file.
168:
169: If the file you specify is actually a directory, Dired is called on
170: that directory (*note Dired::.). This can be inhibited by setting the
171: variable `find-file-run-dired' to `nil'; then it is an error to try to
172: visit a directory.
173:
174: `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that
175: the buffer containing the specified file is selected in another window.
176: The window that was selected before `C-x 4 f' continues to show the
177: same buffer it was already showing. If this command is used when only
178: one window is being displayed, that window is split in two, with one
179: window showing the same before as before, and the other one showing the
180: newly requested file. *Note Windows::.
181:
182: There are two hook variables that allow extensions to modify the
183: operation of visiting files. Visiting a file that does not exist runs
184: the functions in the list `find-file-not-found-hooks'; the value of this
185: variable is expected to be a list of functions, and the functions are
186: called one by one until one of them returns non-`nil'. Any visiting of
187: a file, whether extant or not, expects `find-file-hooks' to contain a
188: list of functions and calls them all, one by one. In both cases the
189: functions receive no arguments. Visiting a nonexistent file runs the
190: `find-file-not-found-hooks' first.
191:
192: You can put a local variable specification at the end of a file which
193: specifies values for Emacs local variables whenever you visit the file.
194: *Note File Variables::.
195:
196:
197: File: emacs, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files
198:
199: Saving Files
200: ============
201:
202: "Saving" a buffer in Emacs means writing its contents back into the
203: file that was visited in the buffer.
204:
205: `C-x C-s'
206: Save the current buffer in its visited file (`save-buffer').
207:
208: `C-x s'
209: Save any or all buffers in their visited files
210: (`save-some-buffers').
211:
212: `M-~'
213: Forget that the current buffer has been changed
214: (`not-modified').
215:
216: `C-x C-w'
217: Save the current buffer in a specified file, and record that file
218: as the one visited in the buffer (`write-file').
219:
220: `M-x set-visited-file-name'
221: Change file the name under which the current buffer will be saved.
222:
223: When you wish to save the file and make your changes permanent, type
224: `C-x C-s' (`save-buffer'). After saving is finished, `C-x C-s' prints
225: a message such as
226:
227: Wrote /u/rms/gnu/gnu.tasks
228:
229: If the selected buffer is not modified (no changes have been made in it
230: since the buffer was created or last saved), saving is not really done,
231: because it would have no effect. Instead, `C-x C-s' prints a message
232: in the echo area saying
233:
234: (No changes need to be written)
235:
236: The command `C-x s' (`save-some-buffers') can save any or all
237: modified buffers. First it asks, for each modified buffer, whether to
238: save it. These questions should be answered with `y' or `n'. `C-x C-c',
239: the key that kills Emacs, invokes `save-some-buffers' and therefore
240: asks the same questions.
241:
242: If you have changed a buffer and do not want the changes to be
243: saved, you should take some action to prevent it. Otherwise, each time
244: you use `save-some-buffers' you are liable to save it by mistake. One
245: thing you can do is type `M-~' (`not-modified'), which clears out the
246: indication that the buffer is modified. If you do this, none of the
247: save commands will believe that the buffer needs to be saved. (`~' is
248: often used as a mathematical symbol for `not'; thus `Meta-~' is `not',
249: metafied.) You could also use `set-visited-file-name' (see below) to
250: mark the buffer as visiting a different file name, one which is not in
251: use for anything important. Alternatively, you can undo all the
252: changes made since the file was visited or saved, by reading the text
253: from the file again. This is called "reverting". *Note Reverting::.
254: You could also undo all the changes by repeating the undo command `C-x
255: u' until you have undone all the changes; but this only works if you
256: have not made more changes than the undo mechanism can remember.
257:
258: `M-x set-visited-file-name' alters the name of the file that the
259: current buffer is visiting. It reads the new file name using the
260: minibuffer. It can be used on a buffer that is not visiting a file,
261: too. The buffer's name is changed to correspond to the file it is now
262: visiting in the usual fashion (unless the new name is in use already
263: for some other buffer; in that case, the buffer name is not changed).
264: `set-visited-file-name' does not save the buffer in the newly visited
265: file; it just alters the records inside Emacs so that, if you save the
266: buffer, it will be saved in that file. It also marks the buffer as
267: "modified" so that `C-x C-s' will save.
268:
269: If you wish to mark the buffer as visiting a different file and save
270: it right away, use `C-x C-w' (`write-file'). It is precisely
271: equivalent to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s'
272: used on a buffer that is not visiting with a file has the same effect
273: as `C-x C-w'; that is, it reads a file name, marks the buffer as
274: visiting that file, and saves it there. The default file name in a
275: buffer that is not visiting a file is made by combining the buffer name
276: with the buffer's default directory.
277:
278: If Emacs is about to save a file and sees that the date of the latest
279: version on disk does not match what Emacs last read or wrote, Emacs
280: notifies you of this fact, because it probably indicates a problem
281: caused by simultaneous editing and requires your immediate attention.
282: *Note Simultaneous Editing: Interlocking.
283:
284: If the variable `require-final-newline' is non-`nil', Emacs puts a
285: newline at the end of any file that doesn't already end in one, every
286: time a file is saved or written.
287:
288: You can implement other ways to write files, and other things to be
289: done before writing them, using the hook variable `write-file-hooks'.
290: The value of this variable should be a list of Lisp functions. When a
291: file is to be written, the functions in the list are called, one by
292: one, with no arguments. If one of them returns a non-`nil' value,
293: Emacs takes this to mean that the file has been written in some
294: suitable fashion; the rest of the functions are not called, and normal
295: writing is not done.
296:
297: * Menu:
298:
299: * Backup:: How Emacs saves the old version of your file.
300: * Interlocking:: How Emacs protects against simultaneous editing
301: of one file by two users.
302:
303:
304: File: emacs, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving
305:
306: Backup Files
307: ------------
308:
309: Because Unix does not provide version numbers in file names,
310: rewriting a file in Unix automatically destroys all record of what the
311: file used to contain. Thus, saving a file from Emacs throws away the
312: old contents of the file--or it would, except that Emacs carefully
313: copies the old contents to another file, called the "backup" file,
314: before actually saving (provided the variable `make-backup-files' is
315: non-`nil'; backup files are not written if this variable is `nil').
316:
317: At your option, Emacs can keep either a single backup file or a
318: series of numbered backup files for each file that you edit.
319:
320: Emacs makes a backup for a file only the first time the file is saved
321: from one buffer. No matter how many times you save a file, its backup
322: file continues to contain the contents from before the file was visited.
323: Normally this means that the backup file contains the contents from
324: before the current editing session; however, if you kill the buffer and
325: then visit the file again, a new backup file will be made by the next
326: save.
327:
328: * Menu:
329:
330: * Names: Backup Names. How backup files are named;
331: Choosing single or numbered backup files.
332: * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
333: * Copying: Backup Copying. Backups can be made by copying or renaming.
334:
335:
336: File: emacs, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup
337:
338: Single or Numbered Backups
339: ..........................
340:
341: If you choose to have a single backup file (this is the default),
342: the backup file's name is constructed by appending `~' to the file name
343: being edited; thus, the backup file for `eval.c' would be `eval.c~'.
344:
345: If you choose to have a series of numbered backup files, backup file
346: names are made by appending `.~', the number, and another `~' to the
347: original file name. Thus, the backup files of `eval.c' would be called
348: `eval.c.~1~', `eval.c.~2~', and so on, through names like
349: `eval.c.~259~' and beyond.
350:
351: If protection stops you from writing backup files under the usual
352: names, the backup file is written as `%backup%~' in your home directory.
353: Only one such file can exist, so only the most recently made such
354: backup is available.
355:
356: The choice of single backup or numbered backups is controlled by the
357: variable `version-control'. Its possible values are
358:
359: `t'
360: Make numbered backups.
361:
362: `nil'
363: Make numbered backups for files that have numbered backups already.
364: Otherwise, make single backups.
365:
366: `never'
367: Do not in any case make numbered backups; always make single
368: backups.
369:
370: `version-control' may be set locally in an individual buffer to control
371: the making of backups for that buffer's file. For example, Rmail mode
372: locally sets `version-control' to `never' to make sure that there is
373: only one backup for an Rmail file. *Note Locals::.
374:
375:
376: File: emacs, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup
377:
378: Automatic Deletion of Backups
379: .............................
380:
381: To prevent unlimited consumption of disk space, Emacs can delete
382: numbered backup versions automatically. Generally Emacs keeps the
383: first few backups and the latest few backups, deleting any in between.
384: This happens every time a new backup is made. The two variables that
385: control the deletion are `kept-old-versions' and `kept-new-versions'.
386: Their values are, respectively the number of oldest (lowest-numbered)
387: backups to keep and the number of newest (highest-numbered) ones to
388: keep, each time a new backup is made. Recall that these values are used
389: just after a new backup version is made; that newly made backup is
390: included in the count in `kept-new-versions'. By default, both
391: variables are 2.
392:
393: If `trim-versions-without-asking' is non-`nil', the excess middle
394: versions are deleted without a murmur. If it is `nil', the default,
395: then you are asked whether the excess middle versions should really be
396: deleted.
397:
398: Dired's `.' (Period) command can also be used to delete old versions.
399: *Note Dired::.
400:
401:
402: File: emacs, Node: Backup Copying, Prev: Backup Deletion, Up: Backup
403:
404: Copying vs. Renaming
405: ....................
406:
407: Backup files can be made by copying the old file or by renaming it.
408: This makes a difference when the old file has multiple names. If the
409: old file is renamed into the backup file, then the alternate names
410: become names for the backup file. If the old file is copied instead,
411: then the alternate names remain names for the file that you are
412: editing, and the contents accessed by those names will be the new
413: contents.
414:
415: The method of making a backup file may also affect the file's owner
416: and group. If copying is used, these do not change. If renaming is
417: used, you become the file's owner, and the file's group becomes the
418: default (different operating systems have different defaults for the
419: group).
420:
421: Having the owner change is usually a good idea, because then the
422: owner always shows who last edited the file. Also, the owners of the
423: backups show who produced those versions. Occasionally there is a file
424: whose owner should not change; it is a good idea for such files to
425: contain local variable lists to set `backup-by-copying-when-mismatch'
426: for them alone (*note File Variables::.).
427:
428: The choice of renaming or copying is controlled by three variables.
429: Normally, renaming is done. If the variable `backup-by-copying' is
430: non-`nil', copying is used. Otherwise, if the variable
431: `backup-by-copying-when-linked' is non-`nil', then copying is done for
432: files that have multiple names, but renaming may still done when the
433: file being edited has only one name. If the variable
434: `backup-by-copying-when-mismatch' is non-`nil', then copying is done if
435: renaming would cause the file's owner or group to change.
436:
437:
438: File: emacs, Node: Interlocking, Prev: Backup, Up: Saving
439:
440: Protection against Simultaneous Editing
441: ---------------------------------------
442:
443: Simultaneous editing occurs when two users visit the same file, both
444: make changes, and then both save them. If nobody were informed that
445: this was happening, whichever user saved first would later find that
446: his changes were lost. On some systems, Emacs notices immediately when
447: the second user starts to change the file, and issues an immediate
448: warning. When this is not possible, or if the second user has gone on
449: to change the file despite the warning, Emacs checks later when the
450: file is saved, and issues a second warning when a user is about to
451: overwrite a file containing another user's changes. If the editing
452: user takes the proper corrective action at this point, he can prevent
453: actual loss of work.
454:
455: When you make the first modification in an Emacs buffer that is
456: visiting a file, Emacs records that you have locked the file. (It does
457: this by writing another file in a directory reserved for this purpose.)
458: The lock is removed when you save the changes. The idea is that the
459: file is locked whenever the buffer is modified. If you begin to modify
460: the buffer while the visited file is locked by someone else, this
461: constitutes a collision, and Emacs asks you what to do. It does this
462: by calling the Lisp function `ask-user-about-lock', which you can
463: redefine for the sake of customization. The standard definition of
464: this function asks you a question and accepts three possible answers:
465:
466: `s'
467: Steal the lock. Whoever was already changing the file loses the
468: lock, and you gain the lock.
469:
470: `p'
471: Proceed. Go ahead and edit the file despite its being locked by
472: someone else.
473:
474: `q'
475: Quit. This causes an error (`file-locked') and the modification
476: you were trying to make in the buffer does not actually take place.
477:
478: Note that locking works on the basis of a file name; if a file has
479: multiple names, Emacs does not realize that the two names are the same
480: file and cannot prevent two user from editing it simultaneously under
481: different names. However, basing locking on names means that Emacs can
482: interlock the editing of new files that will not really exist until
483: they are saved.
484:
485: Some systems are not configured to allow Emacs to make locks. On
486: these systems, Emacs cannot detect trouble in advance, but it still can
487: detect it in time to prevent you from overwriting someone else's
488: changes.
489:
490: Every time Emacs saves a buffer, it first checks the
491: last-modification date of the existing file on disk to see that it has
492: not changed since the file was last visited or saved. If the date does
493: not match, it implies that changes were made in the file in some other
494: way, and these changes are about to be lost if Emacs actually does
495: save. To prevent this, Emacs prints a warning message and asks for
496: confirmation before saving. Occasionally you will know why the file was
497: changed and know that it does not matter; then you can answer `yes' and
498: proceed. Otherwise, you should cancel the save with `C-g' and
499: investigate the situation.
500:
501: The first thing you should do when notified that simultaneous
502: editing has already taken place is to list the directory with `C-u C-x
503: C-d' (*note Directory Listing: ListDir.). This will show the file's
504: current author. You should attempt to contact that person to warn him
505: or her not to continue editing. Often the next step is to save the
506: contents of your Emacs buffer under a different name, and use `diff' to
507: compare the two files.
508:
509: Simultaneous editing checks are also made when you visit with `C-x
510: C-f' a file that is already visited and when you start to modify a file.
511: This is not strictly necessary, but it can cause you to find out about
512: the problem earlier, when perhaps correction takes less work.
513:
514:
515: File: emacs, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files
516:
517: Reverting a Buffer
518: ==================
519:
520: If you have made extensive changes to a file and then change your
521: mind about them, you can get rid of them by reading in the previous
522: version of the file. To do this, use `M-x revert-buffer', which
523: operates on the current buffer. Since this is a very dangerous thing
524: to do, you must confirm it with `yes'.
525:
526: If the current buffer has been auto-saved more recently than it has
527: been saved for real, `revert-buffer' offers to read the auto save file
528: instead of the visited file (*note Auto Save::.). This question comes
529: before the usual request for confirmation, and demands `y' or `n' as an
530: answer. If you have started to type `yes' for confirmation without
531: realizing that the other question was going to be asked, the `y' will
532: answer that question, but the `es' will not be valid confirmation. So
533: you will have a chance to cancel the operation with `C-g' and try it
534: again with the answers that you really intend.
535:
536: `revert-buffer' keeps point at the same distance (measured in
537: characters) from the beginning of the file. If the file was edited only
538: slightly, you will be at approximately the same piece of text after
539: reverting as before. If you have made drastic changes, the same value
540: of point in the old file may address a totally different piece of text.
541:
542: A buffer reverted from its visited file is marked "not modified"
543: until another change is made.
544:
545: Some kinds of buffers whose contents reflect data bases other than
546: files, such as Dired buffers, can also be reverted. For them,
547: reverting means recalculating their contents from the appropriate data
548: base. Buffers created randomly with `C-x b' cannot be reverted;
549: `revert-buffer' reports an error when asked to do so.
550:
551:
552: File: emacs, Node: Auto Save, Next: ListDir, Prev: Reverting, Up: Files
553:
554: Auto-Saving: Protection Against Disasters
555: =========================================
556:
557: Emacs saves all the visited files from time to time (based on
558: counting your keystrokes) without being asked. This is called
559: "auto-saving". It prevents you from losing more than a limited amount
560: of work if the system crashes.
561:
562: When Emacs determines that it is time for auto-saving, each buffer is
563: considered, and is auto-saved if auto-saving is turned on for it and it
564: has been changed since the last time it was auto-saved. If any
565: auto-saving is done, the message `Auto-saving...' is displayed in the
566: echo area until auto-saving is finished. Errors occurring during
567: auto-saving are caught so that they do not interfere with the execution
568: of commands you have been typing.
569:
570: * Menu:
571:
572: * Files: Auto Save Files.
573: * Control: Auto Save Control.
574: * Recover:: Recovering text from auto-save files.
575:
576:
577: File: emacs, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save
578:
579: Auto-Save Files
580: ---------------
581:
582: Auto-saving does not normally save in the files that you visited,
583: because it can be very undesirable to save a program that is in an
584: inconsistent state when you have made half of a planned change.
585: Instead, auto-saving is done in a different file called the "auto-save
586: file", and the visited file is changed only when you request saving
587: explicitly (such as with `C-x C-s').
588:
589: Normally, the auto-save file name is made by appending `#' to the
590: front and rear of the visited file name. Thus, a buffer visiting file
591: `foo.c' would be auto-saved in a file `#foo.c#'. Most buffers that are
592: not visiting files are auto-saved only if you request it explicitly;
593: when they are auto-saved, the auto-save file name is made by appending
594: `#%' to the front and `#' to the rear of buffer name. For example, the
595: `*mail*' buffer in which you compose messages to be sent is auto-saved
596: in a file named `#%*mail*#'. Auto-save file names are made this way
597: unless you reprogram parts of Emacs to do something different (the
598: functions `make-auto-save-file-name' and `auto-save-file-name-p'). The
599: file name to be used for auto-saving in a buffer is calculated when
600: auto-saving is turned on in that buffer.
601:
602: If you want auto-saving to be done in the visited file, set the
603: variable `auto-save-visited-file-name' to be non-`nil'. In this mode,
604: there is really no difference between auto-saving and explicit saving.
605:
606: A buffer's auto-save file is deleted when you save the buffer in its
607: visited file. To inhibit this, set the variable
608: `delete-auto-save-files' to `nil'. Changing the visited file name with
609: `C-x C-w' or `set-visited-file-name' renames any auto-save file to go
610: with the new visited name.
611:
612:
613: File: emacs, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save
614:
615: Controlling Auto-Saving
616: -----------------------
617:
618: Each time you visit a file, auto-saving is turned on for that file's
619: buffer if the variable `auto-save-default' is non-`nil' (but not in
620: batch mode; *note Entering Emacs::.). The default for this variable is
621: `t', so auto-saving is the usual practice for file-visiting buffers.
622: Auto-saving can be turned on or off for any existing buffer with the
623: command `M-x auto-save-mode'. Like other minor mode commands, `M-x
624: auto-save-mode' turns auto-saving on with a positive argument, off with
625: a zero or negative argument; with no argument, it toggles.
626:
627: Emacs does auto-saving periodically based on counting how many
628: characters you have typed since the last time auto-saving was done.
629: The variable `auto-save-interval' specifies how many characters there
630: are between auto-saves. By default, it is 300. Emacs also auto-saves
631: whenever you call the function `do-auto-save'.
632:
633: Emacs also does auto-saving whenever it gets a fatal error. This
634: includes killing the Emacs job with a shell command such as `kill
635: %emacs', or disconnecting a phone line or network connection.
636:
637:
638: File: emacs, Node: Recover, Prev: Auto Save Control, Up: Auto Save
639:
640: Recovering Data from Auto-Saves
641: -------------------------------
642:
643: The way to use the contents of an auto-save file to recover from a
644: loss of data is with the command `M-x recover-file RET FILE RET'. This
645: visits FILE and then (after your confirmation) restores the contents
646: from its auto-save file `#FILE#'. You can then save with `C-x C-s' to
647: put the recovered text into FILE itself. For example, to recover file
648: `foo.c' from its auto-save file `#foo.c#', do:
649:
650: M-x recover-file RET foo.c RET
651: C-x C-s
652:
653: Before asking for confirmation, `M-x recover-file' displays a
654: directory listing describing the specified file and the auto-save file,
655: so you can compare their sizes and dates. If the auto-save file is
656: older, `M-x recover-file' does not offer to read it.
657:
658: Auto-saving is disabled by `M-x recover-file' because using this
659: command implies that the auto-save file contains valuable data from a
660: past session. If you save the data in the visited file and then go on
661: to make new changes, you should turn auto-saving back on with `M-x
662: auto-save-mode'.
663:
664:
665: File: emacs, Node: ListDir, Next: Dired, Prev: Auto Save, Up: Files
666:
667: Listing a File Directory
668: ========================
669:
670: Files are classified by Unix into "directories". A "directory
671: listing" is a list of all the files in a directory. Emacs provides
672: directory listings in brief format (file names only) and verbose format
673: (sizes, dates, and authors included).
674:
675: `C-x C-d DIR-OR-PATTERN'
676: Print a brief directory listing (`list-directory').
677:
678: `C-u C-x C-d DIR-OR-PATTERN'
679: Print a verbose directory listing.
680:
681: The command to print a directory listing is `C-x C-d'
682: (`list-directory'). It reads using the minibuffer a file name which is
683: either a directory to be listed or a wildcard-containing pattern for
684: the files to be listed. For example,
685:
686: C-x C-d /u2/emacs/etc RET
687:
688: lists all the files in directory `/u2/emacs/etc'. An example of
689: specifying a file name pattern is
690:
691: C-x C-d /u2/emacs/src/*.c RET
692:
693: Normally, `C-x C-d' prints a brief directory listing containing just
694: file names. A numeric argument (regardless of value) tells it to print
695: a verbose listing (like `ls -l').
696:
697: The text of a directory listing is obtained by running `ls' in an
698: inferior process. Two Emacs variables control the switches passed to
699: `ls': `list-directory-brief-switches' is a string giving the switches
700: to use in brief listings (`"-CF"' by default), and
701: `list-directory-verbose-switches' is a string giving the switches to
702: use in a verbose listing (`"-l"' by default).
703:
704:
705: File: emacs, Node: Dired, Next: Misc File Ops, Prev: ListDir, Up: Files
706:
707: Dired, the Directory Editor
708: ===========================
709:
710: Dired makes it easy to delete or visit many of the files in a single
711: directory at once. It makes an Emacs buffer containing a listing of the
712: directory. You can use the normal Emacs commands to move around in this
713: buffer, and special Dired commands to operate on the files.
714:
715: * Menu:
716:
717: * Enter: Dired Enter. How to invoke Dired.
718: * Edit: Dired Edit. Editing the Dired buffer.
719: * Deletion: Dired Deletion. Deleting files with Dired.
720: * Immed: Dired Immed. Other file operations through Dired.
721:
722:
723: File: emacs, Node: Dired Enter, Next: Dired Edit, Prev: Dired, Up: Dired
724:
725: Entering Dired
726: --------------
727:
728: To invoke dired, do `C-x d' or `M-x dired'. The command reads a
729: directory name or wildcard file name pattern as a minibuffer argument
730: just like the `list-directory' command, `C-x C-d'. Where `dired'
731: differs from `list-directory' is in naming the buffer after the
732: directory name or the wildcard pattern used for the listing, and putting
733: the buffer into Dired mode so that the special commands of Dired are
734: available in it. The variable `dired-listing-switches' is a string
735: used as an argument to `ls' in making the directory; this string must
736: contain `-l'.
737:
738: To display the Dired buffer in another window rather than in the
739: selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x
740: d'.
741:
742:
743: File: emacs, Node: Dired Edit, Next: Dired Deletion, Prev: Dired Enter, Up: Dired
744:
745: Editing in Dired
746: ----------------
747:
748: Once the Dired buffer exists, you can switch freely between it and
749: other Emacs buffers. Whenever the Dired buffer is selected, certain
750: special commands are provided that operate on files that are listed.
751: The Dired buffer is "read-only", and inserting text in it is not
752: useful, so ordinary printing characters such as `d' and `x' are used
753: for Dired commands. Most Dired commands operate on the file described
754: by the line that point is on. Some commands perform operations
755: immediately; others "flag" the file to be operated on later.
756:
757: Most Dired commands that operate on the current line's file also
758: treat a numeric argument as a repeat count, meaning to act on the files
759: of the next few lines. A negative argument means to operate on the
760: files of the preceding lines, and leave point on the first of those
761: lines.
762:
763: All the usual Emacs cursor motion commands are available in Dired
764: buffers. Some special purpose commands are also provided. The keys
765: `C-n' and `C-p' are redefined so that they try to position the cursor
766: at the beginning of the filename on the line, rather than at the
767: beginning of the line.
768:
769: For extra convenience, SPC and `n' in Dired are equivalent to `C-n'.
770: `p' is equivalent to `C-p'. Moving by lines is done so often in Dired
771: that it deserves to be easy to type. DEL (move up and unflag) is often
772: useful simply for moving up.
773:
774: The `g' command in Dired runs `revert-buffer' to reinitialize the
775: buffer from the actual disk directory and show any changes made in the
776: directory by programs other than Dired. All deletion flags in the Dired
777: buffer are lost when this is done.
778:
779:
780: File: emacs, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired
781:
782: Deleting Files with Dired
783: -------------------------
784:
785: The primary use of Dired is to flag files for deletion and then
786: delete them.
787:
788: `d'
789: Flag this file for deletion.
790:
791: `u'
792: Remove deletion-flag on this line.
793:
794: `DEL'
795: Remove deletion-flag on previous line, moving point to that line.
796:
797: `x'
798: Delete the files that are flagged for deletion.
799:
800: `#'
801: Flag all auto-save files (files whose names start and end with `#')
802: for deletion (*note Auto Save::.).
803:
804: `~'
805: Flag all backup files (files whose names end with `~') for deletion
806: (*note Backup::.).
807:
808: `. (Period)'
809: Flag excess numeric backup files for deletion. The oldest and
810: newest few backup files of any one file are exempt; the middle
811: ones are flagged.
812:
813: You can flag a file for deletion by moving to the line describing the
814: file and typing `d' or `C-d'. The deletion flag is visible as a `D' at
815: the beginning of the line. Point is moved to the beginning of the next
816: line, so that repeated `d' commands flag successive files.
817:
818: The files are flagged for deletion rather than deleted immediately to
819: avoid the danger of deleting a file accidentally. Until you direct
820: Dired to delete the flagged files, you can remove deletion flags using
821: the commands `u' and DEL. `u' works just like `d', but removes flags
822: rather than making flags. DEL moves upward, removing flags; it is like
823: `u' with numeric argument automatically negated.
824:
825: To delete the flagged files, type `x'. This command first displays a
826: list of all the file names flagged for deletion, and requests
827: confirmation with `yes'. Once you confirm, all the flagged files are
828: deleted, and their lines are deleted from the text of the Dired buffer.
829: The shortened Dired buffer remains selected. If you answer `no' or
830: quit with `C-g', you return immediately to Dired, with the deletion
831: flags still present and no files actually deleted.
832:
833: The `#', `~' and `.' commands flag many files for deletion, based on
834: their names. These commands are useful precisely because they do not
835: actually delete any files; you can remove the deletion flags from any
836: flagged files that you really wish to keep.
837:
838: `#' flags for deletion all files that appear to have been made by
839: auto-saving (that is, files whose names begin and end with `#'). `~'
840: flags for deletion all files that appear to have been made as backups
841: for files that were edited (that is, files whose names end with `~').
842:
843: `.' (Period) flags just some of the backup files for deletion: only
844: numeric backups that are not among the oldest few nor the newest few
845: backups of any one file. Normally `dired-kept-versions' (not
846: `kept-new-versions'; that applies only when saving) specifies the
847: number of newest versions of each file to keep, and `kept-old-versions'
848: specifies the number of oldest versions to keep. Period with a positive
849: numeric argument, as in `C-u 3 .', specifies the number of newest
850: versions to keep, overriding `dired-kept-versions'. A negative numeric
851: argument overrides `kept-old-versions', using minus the value of the
852: argument to specify the number of oldest versions of each file to keep.
853:
854:
855: File: emacs, Node: Dired Immed, Prev: Dired Deletion, Up: Dired
856:
857: Immediate File Operations in Dired
858: ----------------------------------
859:
860: Some file operations in Dired take place immediately when they are
861: requested.
862:
863: `c'
864: Copies the file described on the current line. You must supply a
865: file name to copy to, using the minibuffer.
866:
867: `f'
868: Visits the file described on the current line. It is just like
869: typing `C-x C-f' and supplying that file name. If the file on
870: this line is a subdirectory, `f' actually causes Dired to be
871: invoked on that subdirectory. *Note Visiting::.
872:
873: `o'
874: Like `f', but uses another window to display the file's buffer.
875: The Dired buffer remains visible in the first window. This is
876: like using `C-x 4 C-f' to visit the file. *Note Windows::.
877:
878: `r'
879: Renames the file described on the current line. You must supply a
880: file name to rename to, using the minibuffer.
881:
882: `v'
883: Views the file described on this line using `M-x view-file'.
884: Viewing a file is like visiting it, but is slanted toward moving
885: around in the file conveniently and does not allow changing the
886: file. *Note View File: Misc File Ops. Viewing a file that is a
887: directory runs Dired on that directory.
888:
889:
890: File: emacs, Node: Misc File Ops, Prev: Dired, Up: Files
891:
892: Miscellaneous File Operations
893: =============================
894:
895: Emacs has commands for performing many other operations on files.
896: All operate on one file; they do not accept wild card file names.
897:
898: `M-x view-file' allows you to scan or read a file by sequential
899: screenfuls. It reads a file name argument using the minibuffer. After
900: reading the file into an Emacs buffer, `view-file' reads and displays
901: one windowful. You can then type SPC to scroll forward one windowful,
902: or DEL to scroll backward. Various other commands are provided for
903: moving around in the file, but none for changing it; type `C-h' while
904: viewing for a list of them. They are mostly the same as normal Emacs
905: cursor motion commands. To exit from viewing, type `C-c'.
906:
907: `M-x insert-file' inserts a copy of the contents of the specified
908: file into the current buffer at point, leaving point unchanged before
909: the contents and the mark after them. *Note Mark::.
910:
911: `M-x write-region' is the inverse of `M-x insert-file'; it copies
912: the contents of the region into the specified file. `M-x
913: append-to-file' adds the text of the region to the end of the specified
914: file.
915:
916: `M-x delete-file' deletes the specified file, like the `rm' command
917: in the shell. If you are deleting many files in one directory, it may
918: be more convenient to use Dired (*note Dired::.).
919:
920: `M-x rename-file' reads two file names OLD and NEW using the
921: minibuffer, then renames file OLD as NEW. If a file named NEW already
922: exists, you must confirm with `yes' or renaming is not done; this is
923: because renaming causes the old meaning of the name NEW to be lost. If
924: OLD and NEW are on different file systems, the file OLD is copied and
925: deleted.
926:
927: The similar command `M-x add-name-to-file' is used to add an
928: additional name to an existing file without removing its old name. The
929: new name must belong on the same file system that the file is on.
930:
931: `M-x copy-file' reads the file OLD and writes a new file named NEW
932: with the same contents. Confirmation is required if a file named NEW
933: already exists, because copying has the consequence of overwriting the
934: old contents of the file NEW.
935:
936: `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and
937: then creates a symbolic link named LINKNAME and pointing at OLD. The
938: effect is that future attempts to open file LINKNAME will refer to
939: whatever file is named OLD at the time the opening is done, or will get
940: an error if the name OLD is not in use at that time. Confirmation is
941: required when creating the link if LINKNAME is in use. Note that not
942: all systems support symbolic links.
943:
944:
945: File: emacs, Node: Buffers, Next: Windows, Prev: Files, Up: Top
946:
947: Using Multiple Buffers
948: **********************
949:
950: The text you are editing in Emacs resides in an object called a
951: "buffer". Each time you visit a file, a buffer is created to hold the
952: file's text. Each time you invoke Dired, a buffer is created to hold
953: the directory listing. If you send a message with `C-x m', a buffer
954: named `*mail*' is used to hold the text of the message. When you ask
955: for a command's documentation, that appears in a buffer called `*Help*'.
956:
957: At any time, one and only one buffer is "selected". It is also
958: called the "current buffer". Often we say that a command operates on
959: "the buffer" as if there were only one; but really this means that the
960: command operates on the selected buffer (most commands do).
961:
962: When Emacs makes multiple windows, each window has a chosen buffer
963: which is displayed there, but at any time only one of the windows is
964: selected and its chosen buffer is the selected buffer. Each window's
965: mode line displays the name of the buffer that the window is displaying
966: (*note Windows::.).
967:
968: Each buffer has a name, which can be of any length, and you can
969: select any buffer by giving its name. Most buffers are made by
970: visiting files, and their names are derived from the files' names. But
971: you can also create an empty buffer with any name you want. A newly
972: started Emacs has a buffer named `*scratch*' which can be used for
973: evaluating Lisp expressions in Emacs. The distinction between upper
974: and lower case matters in buffer names.
975:
976: Each buffer records individually what file it is visiting, whether
977: it is modified, and what major mode and minor modes are in effect in it
978: (*note Major Modes::.). Any Emacs variable can be made "local to" a
979: particular buffer, meaning its value in that buffer can be different
980: from the value in other buffers. *Note Locals::.
981:
982: * Menu:
983:
984: * Select Buffer:: Creating a new buffer or reselecting an old one.
985: * List Buffers:: Getting a list of buffers that exist.
986: * Misc Buffer:: Renaming; changing read-onliness; copying text.
987: * Kill Buffer:: Killing buffers you no longer need.
988: * Several Buffers:: How to go through the list of all buffers
989: and operate variously on several of them.
990:
991:
992: File: emacs, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers
993:
994: Creating and Selecting Buffers
995: ==============================
996:
997: `C-x b BUFFER RET'
998: Select or create a buffer named BUFFER (`switch-to-buffer').
999:
1000: `C-x 4 b BUFFER RET'
1001: Similar, but select a buffer named BUFFER in another window
1002: (`switch-to-buffer-other-window').
1003:
1004: To select the buffer named BUFNAME, type `C-x b BUFNAME RET'. This
1005: is the command `switch-to-buffer' with argument BUFNAME. You can use
1006: completion on an abbreviation for the buffer name you want (*note
1007: Completion::.). An empty argument to `C-x b' specifies the most
1008: recently selected buffer that is not displayed in any window.
1009:
1010: Most buffers are created by visiting files, or by Emacs commands that
1011: want to display some text, but you can also create a buffer explicitly
1012: by typing `C-x b BUFNAME RET'. This makes a new, empty buffer which is
1013: not visiting any file, and selects it for editing. Such buffers are
1014: used for making notes to yourself. If you try to save one, you are
1015: asked for the file name to use. The new buffer's major mode is
1016: determined by the value of `default-major-mode' (*note Major Modes::.).
1017:
1018: Note that `C-x C-f', and any other command for visiting a file, can
1019: also be used to switch buffers. *Note Visiting::.
1020:
1021:
1022: File: emacs, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers
1023:
1024: Listing Existing Buffers
1025: ========================
1026:
1027: `C-x C-b'
1028: List the existing buffers (`list-buffers').
1029:
1030: To print a list of all the buffers that exist, type `C-x C-b'. Each
1031: line in the list shows one buffer's name, major mode and visited file.
1032: `*' at the beginning of a line indicates the buffer is "modified". If
1033: several buffers are modified, it may be time to save some with `C-x s'
1034: (*note Saving::.). `%' indicates a read-only buffer. `.' marks the
1035: selected buffer. Here is an example of a buffer list:
1036:
1037: MR Buffer Size Mode File
1038: -- ------ ---- ---- ----
1039: .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
1040: *Help* 1287 Fundamental
1041: files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
1042: % RMAIL 64042 RMAIL /u/rms/RMAIL
1043: *% man 747 Dired
1044: net.emacs 343885 Fundamental /u/rms/net.emacs
1045: fileio.c 27691 C /u2/emacs/src/fileio.c
1046: NEWS 67340 Text /u2/emacs/etc/NEWS
1047: *scratch* 0 Lisp Interaction
1048:
1049: Note that the buffer `*Help*' was made by a help request; it is not
1050: visiting any file. The buffer `man' was made by Dired on the directory
1051: `/u2/emacs/man/'.
1052:
1053:
1054: File: emacs, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers
1055:
1056: Miscellaneous Buffer Operations
1057: ===============================
1058:
1059: `C-x C-q'
1060: Toggle read-only status of buffer (`toggle-read-only').
1061:
1062: `M-x rename-buffer'
1063: Change the name of the current buffer.
1064:
1065: `M-x view-buffer'
1066: Scroll through a buffer.
1067:
1068: A buffer can be "read-only", which means that commands to change its
1069: text are not allowed. Normally, read-only buffers are made by
1070: subsystems such as Dired and Rmail that have special commands to
1071: operate on the text; a read-only buffer is also made if you visit a
1072: file that is protected so you cannot write it. If you wish to make
1073: changes in a read-only buffer, use the command `C-x C-q'
1074: (`toggle-read-only'). It makes a read-only buffer writable, and makes
1075: a writable buffer read-only. This works by setting the variable
1076: `buffer-read-only', which has a local value in each buffer and makes
1077: the buffer read-only if its value is non-`nil'.
1078:
1079: `M-x rename-buffer' changes the name of the current buffer. Specify
1080: the new name as a minibuffer argument. There is no default. If you
1081: specify a name that is in use for some other buffer, an error happens
1082: and no renaming is done.
1083:
1084: `M-x view-buffer' is much like `M-x view-file' (*note Misc File
1085: Ops::.) except that it examines an already existing Emacs buffer. View
1086: mode provides commands for scrolling through the buffer conveniently
1087: but not for changing it. When you exit View mode, the value of point
1088: that resulted from your perusal remains in effect.
1089:
1090: The commands `C-x a' (`append-to-buffer') and `M-x insert-buffer'
1091: can be used to copy text from one buffer to another. *Note Accumulating
1092: Text::.
1093:
1094:
1095: File: emacs, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers
1096:
1097: Killing Buffers
1098: ===============
1099:
1100: After you use Emacs for a while, you may accumulate a large number of
1101: buffers. You may then find it convenient to eliminate the ones you no
1102: longer need. There are several commands provided for doing this.
1103:
1104: `C-x k'
1105: Kill a buffer, specified by name (`kill-buffer').
1106:
1107: `M-x kill-some-buffers'
1108: Offer to kill each buffer, one by one.
1109:
1110: `C-x k' (`kill-buffer') kills one buffer, whose name you specify in
1111: the minibuffer. The default, used if you type just RET in the
1112: minibuffer, is to kill the current buffer. If the current buffer is
1113: killed, another buffer is selected; a buffer that has been selected
1114: recently but does not appear in any window now is chosen to be selected.
1115: If the buffer being killed is modified (has unsaved editing) then you
1116: are asked to confirm with `yes' before the buffer is killed.
1117:
1118: The command `M-x kill-some-buffers' asks about each buffer, one by
1119: one. An answer of `y' means to kill the buffer. Killing the current
1120: buffer or a buffer containing unsaved changes selects a new buffer or
1121: asks for confirmation just like `kill-buffer'.
1122:
1123:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.