diff options
Diffstat (limited to 'info/emacs-5')
| -rw-r--r-- | info/emacs-5 | 1123 |
1 files changed, 1123 insertions, 0 deletions
diff --git a/info/emacs-5 b/info/emacs-5 new file mode 100644 index 00000000000..31efa6c1c80 --- /dev/null +++ b/info/emacs-5 @@ -0,0 +1,1123 @@ +This is Info file ../info/emacs, produced by Makeinfo-1.49 from the +input file emacs.texi. + + This file documents the GNU Emacs editor. + + Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the sections entitled "The GNU Manifesto", "Distribution" and "GNU +General Public License" are included exactly as in the original, and +provided that the entire resulting derived work is distributed under the +terms of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the sections entitled "The GNU Manifesto", +"Distribution" and "GNU General Public License" may be included in a +translation approved by the author instead of in the original English. + + +File: emacs, Node: File Names, Next: Visiting, Prev: Files, Up: Files + +File Names +========== + + Most Emacs commands that operate on a file require you to specify the +file name. (Saving and reverting are exceptions; the buffer knows which +file name to use for them.) File names are specified using the +minibuffer (*note Minibuffer::.). "Completion" is available, to make +it easier to specify long file names. *Note Completion::. + + There is always a "default file name" which will be used if you type +just RET, entering an empty argument. Normally the default file name +is the name of the file visited in the current buffer; this makes it +easy to operate on that file with any of the Emacs file commands. + + Each buffer has a default directory, normally the same as the +directory of the file visited in that buffer. When Emacs reads a file +name, if you do not specify a directory, the default directory is used. + 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. The default directory is kept in the variable +`default-directory', which has a separate value in every buffer. + + For example, if the default file name is `/u/rms/gnu/gnu.tasks' then +the default directory is `/u/rms/gnu/'. If you type just `foo', which +does not specify a directory, it is short for `/u/rms/gnu/foo'. +`../.login' would stand for `/u/rms/.login'. `new/foo' would stand for +the filename `/u/rms/gnu/new/foo'. + + The command `M-x pwd' prints the current buffer's default directory, +and the command `M-x cd' sets it (to a value read using the +minibuffer). A buffer's default directory changes only when the `cd' +command is used. A file-visiting buffer's default directory is +initialized to the directory of the file that is visited there. If a +buffer is made randomly with `C-x b', its default directory is copied +from that of the buffer that was current at the time. + + The default directory actually appears in the minibuffer when the +minibuffer becomes active to read a file name. This serves two +purposes: it shows you what the default is, so that you can type a +relative file name and know with certainty what it will mean, and it +allows you to edit the default to specify a different directory. This +insertion of the default directory is inhibited if the variable +`insert-default-directory' is set to `nil'. + + Note that it is legitimate to type an absolute file name after you +enter the minibuffer, ignoring the presence of the default directory +name as part of the text. The final minibuffer contents may look +invalid, but that is not so. *Note Minibuffer File::. + + `$' in a file name is used to substitute environment variables. For +example, if you have used the C shell command `setenv FOO rms/hacks' to +set up an environment variable named `FOO', then you can use +`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for +`/u/rms/hacks/test.c'. (In the Bourne-Again shell, write `export +FOO=rms/hacks' to define `FOO'.) The environment variable name +consists of all the alphanumeric characters after the `$'; +alternatively, it may be enclosed in braces after the `$'. Note that +the `setenv' command affects Emacs only if done before Emacs is started. + + To access a file with `$' in its name, type `$$'. This pair is +converted to a single `$' at the same time as variable substitution is +performed for single `$'. The Lisp function that performs the +substitution is called `substitute-in-file-name'. The substitution is +performed only on filenames read as such using the minibuffer. + + +File: emacs, Node: Visiting, Next: Saving, Prev: File Names, Up: Files + +Visiting Files +============== + +`C-x C-f' + Visit a file (`find-file'). + +`C-x C-v' + Visit a different file instead of the one visited last + (`find-alternate-file'). + +`C-x 4 C-f' + Visit a file, in another window (`find-file-other-window'). Don't + change this window. + + "Visiting" a file means copying its contents into Emacs where you can +edit them. Emacs makes a new buffer for each file that you visit. We +say that the buffer is visiting the file that it was created to hold. +Emacs constructs the buffer name from the file name by throwing away the +directory, keeping just the name proper. For example, a file named +`/usr/rms/emacs.tex' would get a buffer named `emacs.tex'. If there is +already a buffer with that name, a unique name is constructed by +appending `<2>', `<3>', or so on, using the lowest number that makes a +name that is not already in use. + + 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. + + The changes you make with Emacs are made in the Emacs buffer. They +do not take effect in the file that you visited, or any place +permanent, until you "save" the buffer. Saving the buffer means that +Emacs writes the current contents of the buffer into its visited file. +*Note Saving::. + + If a buffer contains changes that have not been saved, the buffer is +said to be "modified". This is important because it implies that some +changes will be lost if the buffer is not saved. The mode line displays +two stars near the left margin if the buffer is modified. + + To visit a file, use the command `C-x C-f' (`find-file'). Follow +the command with the name of the file you wish to visit, terminated by a +RET. + + The file name is read using the minibuffer (*note Minibuffer::.), +with defaulting and completion in the standard manner (*note File +Names::.). While in the minibuffer, you can abort `C-x C-f' by typing +`C-g'. + + Your confirmation that `C-x C-f' has completed successfully is 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 could not be created, or +cannot be read, then an error results. The error message is printed in +the echo area, and includes the file name which Emacs was trying to +visit. + + If you visit a file that is already in Emacs, `C-x C-f' does not make +another copy. It selects the existing buffer containing that file. +However, before doing so, it checks that the file itself has not changed +since you visited or saved it last. If the file has changed, a warning +message is printed. *Note Simultaneous Editing: Interlocking. + + What if you want to create a file? Just visit it. Emacs prints +`(New File)' in the echo area, but in other respects behaves as if you +had visited an existing empty file. If you make any changes and save +them, the file is created. + + If you visit a nonexistent file unintentionally (because you typed +the wrong file name), use the `C-x C-v' (`find-alternate-file') command +to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but +it kills the current buffer (after first offering to save it if it is +modified). `C-x C-v' is allowed even if the current buffer is not +visiting a file. + + If the file you specify is actually a directory, Dired is called on +that directory (*note Dired::.). This can be inhibited by setting the +variable `find-file-run-dired' to `nil'; then it is an error to try to +visit a directory. + + `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that +the buffer containing the specified file is selected in another window. + The window that was selected before `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 before as before, and the other one showing the +newly requested file. *Note Windows::. + + There are two hook variables that allow extensions to modify the +operation of visiting files. Visiting a file that does not exist runs +the functions in the list `find-file-not-found-hooks'; the value of this +variable is expected to be a list of functions, and the functions are +called one by one until one of them returns non-`nil'. Any visiting of +a file, whether extant or not, expects `find-file-hooks' to contain a +list of functions and calls them all, one by one. In both cases the +functions receive no arguments. Visiting a nonexistent file runs the +`find-file-not-found-hooks' first. + + You can put a local variable specification at the end of a file which +specifies values for Emacs local variables whenever you visit the file. +*Note File Variables::. + + +File: emacs, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files + +Saving Files +============ + + "Saving" a buffer in Emacs means writing its contents back into the +file that was visited in the buffer. + +`C-x C-s' + Save the current buffer in its visited file (`save-buffer'). + +`C-x s' + Save any or all buffers in their visited files + (`save-some-buffers'). + +`M-~' + Forget that the current buffer has been changed + (`not-modified'). + +`C-x C-w' + Save the current buffer in a specified file, and record that file + as the one visited in the buffer (`write-file'). + +`M-x set-visited-file-name' + Change file the name under which the current buffer will be saved. + + When you wish to save the file and make your changes permanent, type +`C-x C-s' (`save-buffer'). After saving is finished, `C-x C-s' prints +a message such as + + Wrote /u/rms/gnu/gnu.tasks + +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, `C-x C-s' prints a message +in the echo area saying + + (No changes need to be written) + + The command `C-x s' (`save-some-buffers') can save any or all +modified buffers. First it asks, for each modified buffer, whether to +save it. These questions should be answered with `y' or `n'. `C-x C-c', +the key that kills Emacs, invokes `save-some-buffers' and therefore +asks the same questions. + + If you have changed a buffer and do not want the changes to be +saved, you should take some action to prevent it. Otherwise, each time +you use `save-some-buffers' you are liable to save it by mistake. One +thing you can do is type `M-~' (`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. (`~' is +often used as a mathematical symbol for `not'; thus `Meta-~' is `not', +metafied.) You could also use `set-visited-file-name' (see below) to +mark the buffer as visiting a different file name, one which is not in +use for anything important. Alternatively, you can undo all the +changes made since the file was visited or saved, by reading the text +from the file again. This is called "reverting". *Note Reverting::. +You could also undo all the changes by repeating the undo command `C-x +u' until you have undone all the changes; but this only works if you +have not made more changes than the undo mechanism can remember. + + `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. It can be used on a buffer that is not visiting a file, +too. The buffer's name is changed to correspond to the file it is now +visiting in the usual fashion (unless the new name is in use already +for some other buffer; in that case, the buffer name is not changed). +`set-visited-file-name' does not save the buffer in the newly visited +file; it just alters the records inside Emacs so that, if you save the +buffer, it will be saved in that file. It also marks the buffer as +"modified" so that `C-x C-s' will save. + + If you wish to mark the buffer as visiting a different file and save +it right away, use `C-x C-w' (`write-file'). It is precisely +equivalent to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' +used on a buffer that is not visiting with a file has the same effect +as `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. + + 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. +*Note Simultaneous Editing: Interlocking. + + If the variable `require-final-newline' is non-`nil', Emacs puts a +newline at the end of any file that doesn't already end in one, every +time a file is saved or written. + + You can implement other ways to write files, and other things to be +done before writing them, using the hook variable `write-file-hooks'. +The value of this variable should be a list of Lisp functions. When a +file is to be written, the functions in the list are called, one by +one, with no arguments. If one of them returns a non-`nil' value, +Emacs takes this to mean that the file has been written in some +suitable fashion; the rest of the functions are not called, and normal +writing is not done. + +* Menu: + +* Backup:: How Emacs saves the old version of your file. +* Interlocking:: How Emacs protects against simultaneous editing + of one file by two users. + + +File: emacs, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving + +Backup Files +------------ + + Because Unix does not provide version numbers in file names, +rewriting a file in Unix 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 "backup" file, +before actually saving (provided the variable `make-backup-files' is +non-`nil'; backup files are not written if this variable is `nil'). + + At your option, Emacs can keep either a single backup file or a +series of numbered backup files for each file that you edit. + + Emacs makes a backup for a file only the first time the file is saved +from one buffer. No matter how many times you save a file, its backup +file continues to contain the contents from before the file was visited. +Normally this means that the backup file contains the contents from +before the current editing session; however, if you kill the buffer and +then visit the file again, a new backup file will be made by the next +save. + +* Menu: + +* Names: Backup Names. How backup files are named; + Choosing single or numbered backup files. +* Deletion: Backup Deletion. Emacs deletes excess numbered backups. +* Copying: Backup Copying. Backups can be made by copying or renaming. + + +File: emacs, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup + +Single or Numbered Backups +.......................... + + If you choose to have a single backup file (this is the default), +the backup file's name is constructed by appending `~' to the file name +being edited; thus, the backup file for `eval.c' would be `eval.c~'. + + If you choose to have a series of numbered backup files, backup file +names are made by appending `.~', the number, and another `~' to the +original file name. Thus, the backup files of `eval.c' would be called +`eval.c.~1~', `eval.c.~2~', and so on, through names like +`eval.c.~259~' and beyond. + + If protection stops you from writing backup files under the usual +names, the backup file is written as `%backup%~' in your home directory. +Only one such file can exist, so only the most recently made such +backup is available. + + The choice of single backup or numbered backups is controlled by the +variable `version-control'. Its possible values are + +`t' + Make numbered backups. + +`nil' + Make numbered backups for files that have numbered backups already. + Otherwise, make single backups. + +`never' + Do not in any case make numbered backups; always make single + backups. + +`version-control' may be set locally in an individual buffer to control +the making of backups for that buffer's file. For example, Rmail mode +locally sets `version-control' to `never' to make sure that there is +only one backup for an Rmail file. *Note Locals::. + + +File: emacs, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup + +Automatic Deletion of Backups +............................. + + To prevent unlimited 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. The two variables that +control the deletion are `kept-old-versions' and `kept-new-versions'. +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. Recall that these values are used +just after a new backup version is made; that newly made backup is +included in the count in `kept-new-versions'. By default, both +variables are 2. + + If `trim-versions-without-asking' is non-`nil', the excess middle +versions are deleted without a murmur. If it is `nil', the default, +then you are asked whether the excess middle versions should really be +deleted. + + Dired's `.' (Period) command can also be used to delete old versions. +*Note Dired::. + + +File: emacs, Node: Backup Copying, Prev: Backup Deletion, Up: Backup + +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. 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 `backup-by-copying-when-mismatch' +for them alone (*note File Variables::.). + + The choice of renaming or copying is controlled by three variables. +Normally, renaming is done. If the variable `backup-by-copying' is +non-`nil', copying is used. Otherwise, if the variable +`backup-by-copying-when-linked' is non-`nil', then copying is done for +files that have multiple names, but renaming may still done when the +file being edited has only one name. If the variable +`backup-by-copying-when-mismatch' is non-`nil', then copying is done if +renaming would cause the file's owner or group to change. + + +File: emacs, Node: Interlocking, Prev: Backup, Up: Saving + +Protection against 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. When this is not possible, or if the second user has gone on +to change the file despite the warning, Emacs checks later when the +file is saved, and issues a second warning when a user is about to +overwrite a file containing another user's changes. If the editing +user takes the proper corrective action at this point, he can prevent +actual loss of work. + + When you make the first modification in an Emacs buffer that is +visiting a file, Emacs records that you have locked the file. (It does +this by writing another file in a directory reserved for this purpose.) + The lock is removed when you save the changes. The idea is that the +file is locked whenever the buffer is modified. If you begin to modify +the buffer while the visited file is locked by someone else, this +constitutes a collision, and Emacs asks you what to do. It does this +by calling the Lisp function `ask-user-about-lock', which you can +redefine for the sake of customization. The standard definition of +this function asks you a question and accepts three possible answers: + +`s' + Steal the lock. Whoever was already changing the file loses the + lock, and you gain the lock. + +`p' + Proceed. Go ahead and edit the file despite its being locked by + someone else. + +`q' + Quit. This causes an error (`file-locked') and the modification + you were trying to make in the buffer does not actually take place. + + 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 user 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. On +these systems, Emacs cannot detect trouble in advance, but it still can +detect it in time to prevent you from overwriting someone else's +changes. + + Every time Emacs saves a buffer, it first checks the +last-modification date of the existing file on disk to see 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 prints 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 `yes' and +proceed. Otherwise, you should cancel the save with `C-g' and +investigate the situation. + + The first thing you should do when notified that simultaneous +editing has already taken place is to list the directory with `C-u C-x +C-d' (*note Directory Listing: ListDir.). This will show the file's +current author. You should attempt to contact that person to warn him +or her not to continue editing. Often the next step is to save the +contents of your Emacs buffer under a different name, and use `diff' to +compare the two files. + + Simultaneous editing checks are also made when you visit with `C-x +C-f' a file that is already visited and when you start to modify a file. +This is not strictly necessary, but it can cause you to find out about +the problem earlier, when perhaps correction takes less work. + + +File: emacs, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files + +Reverting a Buffer +================== + + 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 `M-x revert-buffer', which +operates on the current buffer. Since this is a very dangerous thing +to do, you must confirm it with `yes'. + + If the current buffer has been auto-saved more recently than it has +been saved for real, `revert-buffer' offers to read the auto save file +instead of the visited file (*note Auto Save::.). This question comes +before the usual request for confirmation, and demands `y' or `n' as an +answer. If you have started to type `yes' for confirmation without +realizing that the other question was going to be asked, the `y' will +answer that question, but the `es' will not be valid confirmation. So +you will have a chance to cancel the operation with `C-g' and try it +again with the answers that you really intend. + + `revert-buffer' keeps point at the same distance (measured in +characters) from the beginning of the file. If the file was edited only +slightly, you will be at approximately the same piece of text after +reverting as before. If you have made drastic changes, the same value +of point in the old file may address a totally different piece of text. + + A buffer reverted from its visited file is marked "not modified" +until another change is made. + + Some kinds of buffers whose contents reflect data bases other than +files, such as Dired buffers, can also be reverted. For them, +reverting means recalculating their contents from the appropriate data +base. Buffers created randomly with `C-x b' cannot be reverted; +`revert-buffer' reports an error when asked to do so. + + +File: emacs, Node: Auto Save, Next: ListDir, Prev: Reverting, Up: Files + +Auto-Saving: Protection Against Disasters +========================================= + + Emacs saves all the visited files from time to time (based on +counting your keystrokes) without being asked. This is called +"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, each buffer is +considered, and is auto-saved if auto-saving is turned on for it and it +has been changed since the last time it was auto-saved. If any +auto-saving is done, the message `Auto-saving...' is displayed in the +echo area until auto-saving is finished. 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. +* Control: Auto Save Control. +* Recover:: Recovering text from auto-save files. + + +File: emacs, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save + +Auto-Save Files +--------------- + + Auto-saving does not normally save in the files that you visited, +because it can be very undesirable to save a program that is in an +inconsistent state when you have made half of a planned change. +Instead, auto-saving is done in a different file called the "auto-save +file", and the visited file is changed only when you request saving +explicitly (such as with `C-x C-s'). + + Normally, the auto-save file name is made by appending `#' to the +front and rear of the visited file name. Thus, a buffer visiting file +`foo.c' would be auto-saved in a file `#foo.c#'. Most buffers that are +not visiting files are auto-saved only if you request it explicitly; +when they are auto-saved, the auto-save file name is made by appending +`#%' to the front and `#' to the rear of buffer name. For example, the +`*mail*' buffer in which you compose messages to be sent is auto-saved +in a file named `#%*mail*#'. Auto-save file names are made this way +unless you reprogram parts of Emacs to do something different (the +functions `make-auto-save-file-name' and `auto-save-file-name-p'). The +file name to be used for auto-saving in a buffer is calculated when +auto-saving is turned on in that buffer. + + If you want auto-saving to be done in the visited file, set the +variable `auto-save-visited-file-name' to be non-`nil'. In this mode, +there is really no difference between auto-saving and explicit saving. + + A buffer's auto-save file is deleted when you save the buffer in its +visited file. To inhibit this, set the variable +`delete-auto-save-files' to `nil'. Changing the visited file name with +`C-x C-w' or `set-visited-file-name' renames any auto-save file to go +with the new visited name. + + +File: emacs, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save + +Controlling Auto-Saving +----------------------- + + Each time you visit a file, auto-saving is turned on for that file's +buffer if the variable `auto-save-default' is non-`nil' (but not in +batch mode; *note Entering Emacs::.). The default for this variable is +`t', so auto-saving is the usual practice for file-visiting buffers. +Auto-saving can be turned on or off for any existing buffer with the +command `M-x auto-save-mode'. Like other minor mode commands, `M-x +auto-save-mode' turns auto-saving on with a positive argument, off with +a zero or negative argument; with no argument, it toggles. + + Emacs does auto-saving periodically based on counting how many +characters you have typed since the last time auto-saving was done. +The variable `auto-save-interval' specifies how many characters there +are between auto-saves. By default, it is 300. Emacs also auto-saves +whenever you call the function `do-auto-save'. + + Emacs also does auto-saving whenever it gets a fatal error. This +includes killing the Emacs job with a shell command such as `kill +%emacs', or disconnecting a phone line or network connection. + + +File: emacs, Node: Recover, Prev: Auto Save Control, Up: Auto Save + +Recovering Data from Auto-Saves +------------------------------- + + The way to use the contents of an auto-save file to recover from a +loss of data is with the command `M-x recover-file RET FILE RET'. This +visits FILE and then (after your confirmation) restores the contents +from its auto-save file `#FILE#'. You can then save with `C-x C-s' to +put the recovered text into FILE itself. For example, to recover file +`foo.c' from its auto-save file `#foo.c#', do: + + M-x recover-file RET foo.c RET + C-x C-s + + Before asking for confirmation, `M-x recover-file' displays a +directory listing describing the specified file and the auto-save file, +so you can compare their sizes and dates. If the auto-save file is +older, `M-x recover-file' does not offer to read it. + + Auto-saving is disabled by `M-x recover-file' because using this +command implies that the auto-save file contains valuable data from a +past session. If you save the data in the visited file and then go on +to make new changes, you should turn auto-saving back on with `M-x +auto-save-mode'. + + +File: emacs, Node: ListDir, Next: Dired, Prev: Auto Save, Up: Files + +Listing a File Directory +======================== + + Files are classified by Unix into "directories". A "directory +listing" is a list of all the files in a directory. Emacs provides +directory listings in brief format (file names only) and verbose format +(sizes, dates, and authors included). + +`C-x C-d DIR-OR-PATTERN' + Print a brief directory listing (`list-directory'). + +`C-u C-x C-d DIR-OR-PATTERN' + Print a verbose directory listing. + + The command to print a directory listing is `C-x C-d' +(`list-directory'). It reads using the minibuffer a file name which is +either a directory to be listed or a wildcard-containing pattern for +the files to be listed. For example, + + C-x C-d /u2/emacs/etc RET + +lists all the files in directory `/u2/emacs/etc'. An example of +specifying a file name pattern is + + C-x C-d /u2/emacs/src/*.c RET + + Normally, `C-x C-d' prints a brief directory listing containing just +file names. A numeric argument (regardless of value) tells it to print +a verbose listing (like `ls -l'). + + The text of a directory listing is obtained by running `ls' in an +inferior process. Two Emacs variables control the switches passed to +`ls': `list-directory-brief-switches' is a string giving the switches +to use in brief listings (`"-CF"' by default), and +`list-directory-verbose-switches' is a string giving the switches to +use in a verbose listing (`"-l"' by default). + + +File: emacs, Node: Dired, Next: Misc File Ops, Prev: ListDir, Up: Files + +Dired, the Directory Editor +=========================== + + Dired makes it easy to delete or visit many of the files in a single +directory at once. It makes an Emacs buffer containing a listing of the +directory. You can use the normal Emacs commands to move around in this +buffer, and special Dired commands to operate on the files. + +* Menu: + +* Enter: Dired Enter. How to invoke Dired. +* Edit: Dired Edit. Editing the Dired buffer. +* Deletion: Dired Deletion. Deleting files with Dired. +* Immed: Dired Immed. Other file operations through Dired. + + +File: emacs, Node: Dired Enter, Next: Dired Edit, Prev: Dired, Up: Dired + +Entering Dired +-------------- + + To invoke dired, do `C-x d' or `M-x dired'. The command reads a +directory name or wildcard file name pattern as a minibuffer argument +just like the `list-directory' command, `C-x C-d'. Where `dired' +differs from `list-directory' is in naming the buffer after the +directory name or the wildcard pattern used for the listing, and putting +the buffer into Dired mode so that the special commands of Dired are +available in it. The variable `dired-listing-switches' is a string +used as an argument to `ls' in making the directory; this string must +contain `-l'. + + To display the Dired buffer in another window rather than in the +selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x +d'. + + +File: emacs, Node: Dired Edit, Next: Dired Deletion, Prev: Dired Enter, Up: Dired + +Editing in Dired +---------------- + + Once the Dired buffer exists, you can switch freely between it and +other Emacs buffers. Whenever the Dired buffer is selected, certain +special commands are provided that operate on files that are listed. +The Dired buffer is "read-only", and inserting text in it is not +useful, so ordinary printing characters such as `d' and `x' are used +for Dired commands. Most Dired commands operate on the file described +by the line that point is on. Some commands perform operations +immediately; others "flag" the file to be operated on later. + + Most Dired commands that operate on the current line's file also +treat a numeric argument as a repeat count, meaning to act on the files +of the next few lines. A negative argument means to operate on the +files of the preceding lines, and leave point on the first of those +lines. + + All the usual Emacs cursor motion commands are available in Dired +buffers. Some special purpose commands are also provided. The keys +`C-n' and `C-p' are redefined so that they try to position the cursor +at the beginning of the filename on the line, rather than at the +beginning of the line. + + For extra convenience, SPC and `n' in Dired are equivalent to `C-n'. + `p' is equivalent to `C-p'. Moving by lines is done so often in Dired +that it deserves to be easy to type. DEL (move up and unflag) is often +useful simply for moving up. + + The `g' command in Dired runs `revert-buffer' to reinitialize the +buffer from the actual disk directory and show any changes made in the +directory by programs other than Dired. All deletion flags in the Dired +buffer are lost when this is done. + + +File: emacs, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired + +Deleting Files with Dired +------------------------- + + The primary use of Dired is to flag files for deletion and then +delete them. + +`d' + Flag this file for deletion. + +`u' + Remove deletion-flag on this line. + +`DEL' + Remove deletion-flag on previous line, moving point to that line. + +`x' + Delete the files that are flagged for deletion. + +`#' + Flag all auto-save files (files whose names start and end with `#') + for deletion (*note Auto Save::.). + +`~' + Flag all backup files (files whose names end with `~') for deletion + (*note Backup::.). + +`. (Period)' + Flag excess numeric backup files for deletion. The oldest and + newest few backup files of any one file are exempt; the middle + ones are flagged. + + You can flag a file for deletion by moving to the line describing the +file and typing `d' or `C-d'. The deletion flag is visible as a `D' at +the beginning of the line. Point is moved to the beginning of the next +line, so that repeated `d' commands flag successive files. + + The files are flagged for deletion rather than deleted immediately to +avoid the danger of deleting a file accidentally. Until you direct +Dired to delete the flagged files, you can remove deletion flags using +the commands `u' and DEL. `u' works just like `d', but removes flags +rather than making flags. DEL moves upward, removing flags; it is like +`u' with numeric argument automatically negated. + + To delete the flagged files, type `x'. This command first displays a +list of all the file names flagged for deletion, and requests +confirmation with `yes'. Once you confirm, all the flagged files are +deleted, and their lines are deleted from the text of the Dired buffer. + The shortened Dired buffer remains selected. If you answer `no' or +quit with `C-g', you return immediately to Dired, with the deletion +flags still present and no files actually deleted. + + The `#', `~' and `.' commands flag many files for deletion, based on +their names. These commands are useful precisely because they do not +actually delete any files; you can remove the deletion flags from any +flagged files that you really wish to keep. + + `#' flags for deletion all files that appear to have been made by +auto-saving (that is, files whose names begin and end with `#'). `~' +flags for deletion all files that appear to have been made as backups +for files that were edited (that is, files whose names end with `~'). + + `.' (Period) flags just some of the backup files for deletion: only +numeric backups that are not among the oldest few nor the newest few +backups of any one file. Normally `dired-kept-versions' (not +`kept-new-versions'; that applies only when saving) specifies the +number of newest versions of each file to keep, and `kept-old-versions' +specifies the number of oldest versions to keep. Period with a positive +numeric argument, as in `C-u 3 .', specifies the number of newest +versions to keep, overriding `dired-kept-versions'. A negative numeric +argument overrides `kept-old-versions', using minus the value of the +argument to specify the number of oldest versions of each file to keep. + + +File: emacs, Node: Dired Immed, Prev: Dired Deletion, Up: Dired + +Immediate File Operations in Dired +---------------------------------- + + Some file operations in Dired take place immediately when they are +requested. + +`c' + Copies the file described on the current line. You must supply a + file name to copy to, using the minibuffer. + +`f' + Visits the file described on the current line. It is just like + typing `C-x C-f' and supplying that file name. If the file on + this line is a subdirectory, `f' actually causes Dired to be + invoked on that subdirectory. *Note Visiting::. + +`o' + Like `f', but uses another window to display the file's buffer. + The Dired buffer remains visible in the first window. This is + like using `C-x 4 C-f' to visit the file. *Note Windows::. + +`r' + Renames the file described on the current line. You must supply a + file name to rename to, using the minibuffer. + +`v' + Views the file described on this line using `M-x view-file'. + Viewing a file is like visiting it, but is slanted toward moving + around in the file conveniently and does not allow changing the + file. *Note View File: Misc File Ops. Viewing a file that is a + directory runs Dired on that directory. + + +File: emacs, Node: Misc File Ops, Prev: Dired, Up: Files + +Miscellaneous File Operations +============================= + + Emacs has commands for performing many other operations on files. +All operate on one file; they do not accept wild card file names. + + `M-x view-file' allows you to scan or read a file by sequential +screenfuls. It reads a file name argument using the minibuffer. After +reading the file into an Emacs buffer, `view-file' reads and displays +one windowful. You can then type SPC to scroll forward one windowful, +or DEL to scroll backward. Various other commands are provided for +moving around in the file, but none for changing it; type `C-h' while +viewing for a list of them. They are mostly the same as normal Emacs +cursor motion commands. To exit from viewing, type `C-c'. + + `M-x insert-file' inserts a copy of the contents of the specified +file into the current buffer at point, leaving point unchanged before +the contents and the mark after them. *Note Mark::. + + `M-x write-region' is the inverse of `M-x insert-file'; it copies +the contents of the region into the specified file. `M-x +append-to-file' adds the text of the region to the end of the specified +file. + + `M-x delete-file' deletes the specified file, like the `rm' command +in the shell. If you are deleting many files in one directory, it may +be more convenient to use Dired (*note Dired::.). + + `M-x rename-file' reads two file names OLD and NEW using the +minibuffer, then renames file OLD as NEW. If a file named NEW already +exists, you must confirm with `yes' or renaming is not done; this is +because renaming causes the old meaning of the name NEW to be lost. If +OLD and NEW are on different file systems, the file OLD is copied and +deleted. + + The similar command `M-x add-name-to-file' is used to add an +additional name to an existing file without removing its old name. The +new name must belong on the same file system that the file is on. + + `M-x copy-file' reads the file OLD and writes a new file named NEW +with the same contents. Confirmation is required if a file named NEW +already exists, because copying has the consequence of overwriting the +old contents of the file NEW. + + `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and +then creates a symbolic link named LINKNAME and pointing at OLD. The +effect is that future attempts to open file LINKNAME will refer to +whatever file is named OLD at the time the opening is done, or will get +an error if the name OLD is not in use at that time. Confirmation is +required when creating the link if LINKNAME is in use. Note that not +all systems support symbolic links. + + +File: emacs, Node: Buffers, Next: Windows, Prev: Files, Up: Top + +Using Multiple Buffers +********************** + + The text you are editing in Emacs resides in an object called a +"buffer". Each time you visit a file, a buffer is created to hold the +file's text. Each time you invoke Dired, a buffer is created to hold +the directory listing. If you send a message with `C-x m', a buffer +named `*mail*' is used to hold the text of the message. When you ask +for a command's documentation, that appears in a buffer called `*Help*'. + + At any time, one and only one buffer is "selected". It is also +called the "current buffer". Often we say that a command operates on +"the buffer" as if there were only one; but really this means that the +command operates on the selected buffer (most commands do). + + When Emacs makes multiple windows, each window has a chosen buffer +which is displayed there, but at any time only one of the windows is +selected and its chosen buffer is the selected buffer. Each window's +mode line displays the name of the buffer that the window is displaying +(*note Windows::.). + + Each buffer has a name, which can be of any length, and you can +select any buffer by giving its name. Most buffers are made by +visiting files, and their names are derived from the files' names. But +you can also create an empty buffer with any name you want. A newly +started Emacs has a buffer named `*scratch*' which can be used for +evaluating Lisp expressions in Emacs. The distinction between upper +and lower case matters in buffer names. + + Each buffer records individually what file it is visiting, whether +it is modified, and what major mode and minor modes are in effect in it +(*note Major Modes::.). Any Emacs variable can be made "local to" a +particular buffer, meaning its value in that buffer can be different +from the value in other buffers. *Note Locals::. + +* Menu: + +* Select Buffer:: Creating a new buffer or reselecting an old one. +* List Buffers:: Getting a list of buffers that exist. +* Misc Buffer:: Renaming; changing read-onliness; copying text. +* Kill Buffer:: Killing buffers you no longer need. +* Several Buffers:: How to go through the list of all buffers + and operate variously on several of them. + + +File: emacs, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers + +Creating and Selecting Buffers +============================== + +`C-x b BUFFER RET' + Select or create a buffer named BUFFER (`switch-to-buffer'). + +`C-x 4 b BUFFER RET' + Similar, but select a buffer named BUFFER in another window + (`switch-to-buffer-other-window'). + + To select the buffer named BUFNAME, type `C-x b BUFNAME RET'. This +is the command `switch-to-buffer' with argument BUFNAME. You can use +completion on an abbreviation for the buffer name you want (*note +Completion::.). An empty argument to `C-x b' specifies the most +recently selected buffer that is not displayed in any window. + + Most buffers are created by visiting files, or by Emacs commands that +want to display some text, but you can also create a buffer explicitly +by typing `C-x b BUFNAME RET'. This makes a new, empty buffer which is +not visiting any file, and selects it for editing. Such buffers are +used for making notes to yourself. If you try to save one, you are +asked for the file name to use. The new buffer's major mode is +determined by the value of `default-major-mode' (*note Major Modes::.). + + Note that `C-x C-f', and any other command for visiting a file, can +also be used to switch buffers. *Note Visiting::. + + +File: emacs, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers + +Listing Existing Buffers +======================== + +`C-x C-b' + List the existing buffers (`list-buffers'). + + To print a list of all the buffers that exist, type `C-x C-b'. Each +line in the list shows one buffer's name, major mode and visited file. +`*' at the beginning of a line indicates the buffer is "modified". If +several buffers are modified, it may be time to save some with `C-x s' +(*note Saving::.). `%' indicates a read-only buffer. `.' marks the +selected buffer. Here is an example of a buffer list: + + MR Buffer Size Mode File + -- ------ ---- ---- ---- + .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex + *Help* 1287 Fundamental + files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el + % RMAIL 64042 RMAIL /u/rms/RMAIL + *% man 747 Dired + net.emacs 343885 Fundamental /u/rms/net.emacs + fileio.c 27691 C /u2/emacs/src/fileio.c + NEWS 67340 Text /u2/emacs/etc/NEWS + *scratch* 0 Lisp Interaction + +Note that the buffer `*Help*' was made by a help request; it is not +visiting any file. The buffer `man' was made by Dired on the directory +`/u2/emacs/man/'. + + +File: emacs, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers + +Miscellaneous Buffer Operations +=============================== + +`C-x C-q' + Toggle read-only status of buffer (`toggle-read-only'). + +`M-x rename-buffer' + Change the name of the current buffer. + +`M-x view-buffer' + Scroll through a buffer. + + A buffer can be "read-only", which means that commands to change its +text are not allowed. Normally, read-only buffers are made by +subsystems such as Dired and Rmail that have special commands to +operate on the text; a read-only buffer is also made if you visit a +file that is protected so you cannot write it. If you wish to make +changes in a read-only buffer, use the command `C-x C-q' +(`toggle-read-only'). It makes a read-only buffer writable, and makes +a writable buffer read-only. This works by setting the variable +`buffer-read-only', which has a local value in each buffer and makes +the buffer read-only if its value is non-`nil'. + + `M-x rename-buffer' changes the name of the current buffer. Specify +the new name as a minibuffer argument. There is no default. If you +specify a name that is in use for some other buffer, an error happens +and no renaming is done. + + `M-x view-buffer' is much like `M-x view-file' (*note Misc File +Ops::.) except that it examines an already existing Emacs buffer. View +mode provides commands for scrolling through the buffer conveniently +but not for changing it. When you exit View mode, the value of point +that resulted from your perusal remains in effect. + + The commands `C-x a' (`append-to-buffer') and `M-x insert-buffer' +can be used to copy text from one buffer to another. *Note Accumulating +Text::. + + +File: emacs, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers + +Killing Buffers +=============== + + After you use Emacs for a while, you may accumulate a large number of +buffers. You may then find it convenient to eliminate the ones you no +longer need. There are several commands provided for doing this. + +`C-x k' + Kill a buffer, specified by name (`kill-buffer'). + +`M-x kill-some-buffers' + Offer to kill each buffer, one by one. + + `C-x k' (`kill-buffer') kills one buffer, whose name you specify in +the minibuffer. The default, used if you type just RET in the +minibuffer, is to kill the current buffer. If the current buffer is +killed, another buffer is selected; a buffer that has been selected +recently but does not appear in any window now is chosen to be selected. +If the buffer being killed is modified (has unsaved editing) then you +are asked to confirm with `yes' before the buffer is killed. + + The command `M-x kill-some-buffers' asks about each buffer, one by +one. An answer of `y' means to kill the buffer. Killing the current +buffer or a buffer containing unsaved changes selects a new buffer or +asks for confirmation just like `kill-buffer'. + +
\ No newline at end of file |