1This is Info file ../info/emacs, produced by Makeinfo-1.54 from the 2input file emacs.texi. 3 4 5File: emacs, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace 6 7Replace Commands and Case 8------------------------- 9 10 If the arguments to a replace command are in lower case, it preserves 11case when it makes a replacement. Thus, the command 12 13 M-x replace-string RET foo RET bar RET 14 15replaces a lower case `foo' with a lower case `bar', `FOO' with `BAR', 16and `Foo' with `Bar'. If upper case letters are used in the second 17argument, they remain upper case every time that argument is inserted. 18If upper case letters are used in the first argument, the second 19argument is always substituted exactly as given, with no case 20conversion. Likewise, if the variable `case-replace' is set to `nil', 21replacement is done without case conversion. If `case-fold-search' is 22set to `nil', case is significant in matching occurrences of `foo' to 23replace; this also inhibits case conversion of the replacement string. 24 25 26File: emacs, Node: Query Replace, Prev: Replacement and Case, Up: Replace 27 28Query Replace 29------------- 30 31`M-% STRING RET NEWSTRING RET' 32`M-x query-replace RET STRING RET NEWSTRING RET' 33 Replace some occurrences of STRING with NEWSTRING. 34 35`M-x query-replace-regexp RET REGEXP RET NEWSTRING RET' 36 Replace some matches for REGEXP with NEWSTRING. 37 38 If you want to change only some of the occurrences of `foo' to 39`bar', not all of them, then you cannot use an ordinary 40`replace-string'. Instead, use `M-%' (`query-replace'). This command 41finds occurrences of `foo' one by one, displays each occurrence and 42asks you whether to replace it. A numeric argument to `query-replace' 43tells it to consider only occurrences that are bounded by 44word-delimiter characters. This preserves case, just like 45`replace-string', provided `case-replace' is non-`nil', as it normally 46is. 47 48 Aside from querying, `query-replace' works just like 49`replace-string', and `query-replace-regexp' works just like 50`replace-regexp'. The shortest way to type this command name is `M-x 51que SPC SPC SPC RET'. 52 53 The things you can type when you are shown an occurrence of STRING 54or a match for REGEXP are: 55 56`SPC' 57 to replace the occurrence with NEWSTRING. 58 59`DEL' 60 to skip to the next occurrence without replacing this one. 61 62`, (Comma)' 63 to replace this occurrence and display the result. You are then 64 asked for another input character, except that since the 65 replacement has already been made, DEL and SPC are equivalent. 66 You could type `C-r' at this point (see below) to alter the 67 replaced text. You could also type `C-x u' to undo the 68 replacement; this exits the `query-replace', so if you want to do 69 further replacement you must use `C-x ESC ESC RET' to restart 70 (*note Repetition::.). 71 72`RET' 73 to exit without doing any more replacements. 74 75`. (Period)' 76 to replace this occurrence and then exit without searching for more 77 occurrences. 78 79`!' 80 to replace all remaining occurrences without asking again. 81 82`^' 83 to go back to the position of the previous occurrence (or what 84 used to be an occurrence), in case you changed it by mistake. 85 This works by popping the mark ring. Only one `^' in a row is 86 allowed, because only one previous replacement position is kept 87 during `query-replace'. 88 89`C-r' 90 to enter a recursive editing level, in case the occurrence needs 91 to be edited rather than just replaced with NEWSTRING. When you 92 are done, exit the recursive editing level with `C-M-c' to proceed 93 to the next occurrence. *Note Recursive Edit::. 94 95`C-w' 96 to delete the occurrence, and then enter a recursive editing level 97 as in `C-r'. Use the recursive edit to insert text to replace the 98 deleted occurrence of STRING. When done, exit the recursive 99 editing level with `C-M-c' to proceed to the next occurrence. 100 101`C-l' 102 to redisplay the screen. Then you must type another character to 103 specify what to do with this occurrence. 104 105`C-h' 106 to display a message summarizing these options. Then you must type 107 another character to specify what to do with this occurrence. 108 109 Some other characters are aliases for the ones listed above: `y', 110`n' and `q' are equivalent to SPC, DEL and RET. 111 112 Aside from this, any other character exits the `query-replace', and 113is then reread as part of a key sequence. Thus, if you type `C-k', it 114exits the `query-replace' and then kills to end of line. 115 116 To restart a `query-replace' once it is exited, use `C-x ESC ESC', 117which repeats the `query-replace' because it used the minibuffer to 118read its arguments. *Note C-x ESC ESC: Repetition. 119 120 See also *Note Transforming File Names::, for Dired commands to 121rename, copy, or link files by replacing regexp matches in file names. 122 123 124File: emacs, Node: Other Repeating Search, Prev: Replace, Up: Search 125 126Other Search-and-Loop Commands 127============================== 128 129 Here are some other commands that find matches for a regular 130expression. They all operate from point to the end of the buffer. 131 132`M-x occur RET REGEXP RET' 133 Print each line that follows point and contains a match for 134 REGEXP. A numeric argument specifies the number of context lines 135 to print before and after each matching line; the default is none. 136 137 The buffer `*Occur*' containing the output serves as a menu for 138 finding the occurrences in their original context. Find an 139 occurrence as listed in `*Occur*', position point there and type 140 `C-c C-c'; this switches to the buffer that was searched and moves 141 point to the original of the same occurrence. 142 143`M-x list-matching-lines' 144 Synonym for `M-x occur'. 145 146`M-x count-matches RET REGEXP RET' 147 Print the number of matches for REGEXP after point. 148 149`M-x flush-lines RET REGEXP RET' 150 Delete each line that follows point and contains a match for 151 REGEXP. 152 153`M-x keep-lines RET REGEXP RET' 154 Delete each line that follows point and does not contain a match 155 for REGEXP. 156 157 158File: emacs, Node: Fixit, Next: Files, Prev: Search, Up: Top 159 160Commands for Fixing Typos 161************************* 162 163 In this chapter we describe the commands that are especially useful 164for the times when you catch a mistake in your text just after you have 165made it, or change your mind while composing text on line. 166 167* Menu: 168 169* Kill Errors:: Commands to kill a batch of recently entered text. 170* Transpose:: Exchanging two characters, words, lines, lists... 171* Fixing Case:: Correcting case of last word entered. 172* Spelling:: Apply spelling checker to a word, or a whole file. 173 174 175File: emacs, Node: Kill Errors, Next: Transpose, Up: Fixit 176 177Killing Your Mistakes 178===================== 179 180`DEL' 181 Delete last character (`delete-backward-char'). 182 183`M-DEL' 184 Kill last word (`backward-kill-word'). 185 186`C-x DEL' 187 Kill to beginning of sentence (`backward-kill-sentence'). 188 189 The DEL character (`delete-backward-char') is the most important 190correction command. When used among graphic (self-inserting) 191characters, it can be thought of as canceling the last character typed. 192 193 When your mistake is longer than a couple of characters, it might be 194more convenient to use `M-DEL' or `C-x DEL'. `M-DEL' kills back to the 195start of the last word, and `C-x DEL' kills back to the start of the 196last sentence. `C-x DEL' is particularly useful when you change your 197mind about the phrasing of the text you are writing. `M-DEL' and `C-x 198DEL' save the killed text for `C-y' and `M-y' to retrieve. *Note 199Yanking::. 200 201 `M-DEL' is often useful even when you have typed only a few 202characters wrong, if you know you are confused in your typing and aren't 203sure exactly what you typed. At such a time, you cannot correct with 204DEL except by looking at the screen to see what you did. It requires 205less thought to kill the whole word and start over again. 206 207 208File: emacs, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit 209 210Transposing Text 211================ 212 213`C-t' 214 Transpose two characters (`transpose-chars'). 215 216`M-t' 217 Transpose two words (`transpose-words'). 218 219`C-M-t' 220 Transpose two balanced expressions (`transpose-sexps'). 221 222`C-x C-t' 223 Transpose two lines (`transpose-lines'). 224 225 The common error of transposing two characters can be fixed, when 226they are adjacent, with the `C-t' command (`transpose-chars'). 227Normally, `C-t' transposes the two characters on either side of point. 228When given at the end of a line, rather than transposing the last 229character of the line with the newline, which would be useless, `C-t' 230transposes the last two characters on the line. So, if you catch your 231transposition error right away, you can fix it with just a `C-t'. If 232you don't catch it so fast, you must move the cursor back to between 233the two transposed characters. If you transposed a space with the last 234character of the word before it, the word motion commands are a good 235way of getting there. Otherwise, a reverse search (`C-r') is often the 236best way. *Note Search::. 237 238 `M-t' (`transpose-words') transposes the word before point with the 239word after point. It moves point forward over a word, dragging the 240word preceding or containing point forward as well. The punctuation 241characters between the words do not move. For example, `FOO, BAR' 242transposes into `BAR, FOO' rather than `BAR FOO,'. 243 244 `C-M-t' (`transpose-sexps') is a similar command for transposing two 245expressions (*note Lists::.), and `C-x C-t' (`transpose-lines') 246exchanges lines. They work like `M-t' except in determining the 247division of the text into syntactic units. 248 249 A numeric argument to a transpose command serves as a repeat count: 250it tells the transpose command to move the character (word, sexp, line) 251before or containing point across several other characters (words, 252sexps, lines). For example, `C-u 3 C-t' moves the character before 253point forward across three other characters. It would change 254`f-!-oobar' into `oobf-!-ar'. This is equivalent to repeating `C-t' 255three times. `C-u - 4 M-t' moves the word before point backward across 256four words. `C-u - C-M-t' would cancel the effect of plain `C-M-t'. 257 258 A numeric argument of zero is assigned a special meaning (because 259otherwise a command with a repeat count of zero would do nothing): to 260transpose the character (word, sexp, line) ending after point with the 261one ending after the mark. 262 263 264File: emacs, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit 265 266Case Conversion 267=============== 268 269`M-- M-l' 270 Convert last word to lower case. Note `Meta--' is Meta-minus. 271 272`M-- M-u' 273 Convert last word to all upper case. 274 275`M-- M-c' 276 Convert last word to lower case with capital initial. 277 278 A very common error is to type words in the wrong case. Because of 279this, the word case-conversion commands `M-l', `M-u' and `M-c' have a 280special feature when used with a negative argument: they do not move the 281cursor. As soon as you see you have mistyped the last word, you can 282simply case-convert it and go on typing. *Note Case::. 283 284 285File: emacs, Node: Spelling, Prev: Fixing Case, Up: Fixit 286 287Checking and Correcting Spelling 288================================ 289 290 This section describes the commands to check the spelling of a single 291word or of a portion of a buffer. These commands work with the spelling 292checker program Ispell, which is not part of Emacs. *Note Ispell: (The 293Ispell Manual)Top. 294 295`M-$' 296 Check and correct spelling of word at point (`ispell-word'). 297 298`M-x ispell-buffer' 299 Check and correct spelling of each word in the buffer. 300 301`M-x ispell-region' 302 Check and correct spelling of each word in the region. 303 304`M-x ispell-complete-word' 305 Complete the word before point based on the spelling dictionary. 306 307`M-x ispell-kill-ispell' 308 Kill the Ispell subprocess. 309 310 To check the spelling of the word around or next to point, and 311optionally correct it as well, use the command `M-$' (`ispell-word'). 312If the word is not correct, the command offers you various alternatives 313for what to do about it. 314 315 To check the entire current buffer, use `M-x ispell-buffer'. Use 316`M-x ispell-region' to check just the current region. Each time these 317commands encounter an incorrect word, they ask you what to do. 318 319 Whenever one of these commands finds an incorrect word, it displays a 320list of alternatives, usually including several "near-misses"--words 321that are close to the word being checked. Here are the valid responses: 322 323`SPC' 324 Skip this word--continue to consider it incorrect, but don't 325 change it here. 326 327`r NEW RET' 328 Replace the word (just this time) with NEW. 329 330`R NEW RET' 331 Replace the word with NEW, and do a `query-replace' so you can 332 replace it elsewhere in the buffer if you wish. 333 334`DIGIT' 335 Replace the word (just this time) with one of the displayed 336 near-misses. Each near-miss is listed with a digit; type that 337 digit to select it. 338 339`a' 340 Accept the incorrect word--treat it as correct, but only in this 341 editing session. 342 343`A' 344 Accept the incorrect word--treat it as correct, but only in this 345 editing session and for this buffer. 346 347`i' 348 Insert this word in your private dictionary file so that Ispell 349 will consider it correct it from now on, even in future sessions. 350 351`m' 352 Like `i', but you can also specify dictionary completion 353 information. 354 355`l WORD RET' 356 Look in the dictionary for words that match WORD. These words 357 become the new list of "near-misses"; you can select one of them to 358 replace with by typing a digit. You can use `*' in WORD as a 359 wildcard. 360 361`C-g' 362 Quit interactive spell checking. You can restart it again 363 afterward with `C-u M-$'. 364 365`X' 366 Same as `C-g'. 367 368`C-z' 369 This key has its normal command meaning (suspend Emacs or iconify 370 this frame). 371 372 The command `ispell-complete-word', which is bound to the key 373`M-TAB' in Text mode and related modes, shows a list of completions 374based on spelling correction. Insert the beginning of a word, and then 375type `M-TAB'; the command displays a completion list window. To choose 376one of the completions listed, click `Mouse-2' on it, or move the 377cursor there in the completions window and type RET. *Note Text Mode::. 378 379 Once started, the Ispell subprocess continues to run (waiting for 380something to do), so that subsequent spell checking commands complete 381more quickly. If you want to get rid of the Ispell process, use `M-x 382ispell-kill-ispell'. This is not usually necessary, since the process 383uses no time except when you do spelling correction. 384 385 386File: emacs, Node: Files, Next: Buffers, Prev: Fixit, Up: Top 387 388File Handling 389************* 390 391 The basic unit of stored data in Unix is the "file". To edit a file, 392you must tell Emacs to examine the file and prepare a buffer containing 393a copy of the file's text. This is called "visiting" the file. Editing 394commands apply directly to text in the buffer; that is, to the copy 395inside Emacs. Your changes appear in the file itself only when you 396"save" the buffer back into the file. 397 398 In addition to visiting and saving files, Emacs can delete, copy, 399rename, and append to files, keep multiple versions of them, and operate 400on file directories. 401 402* Menu: 403 404* File Names:: How to type and edit file name arguments. 405* Visiting:: Visiting a file prepares Emacs to edit the file. 406* Saving:: Saving makes your changes permanent. 407* Reverting:: Reverting cancels all the changes not saved. 408* Auto Save:: Auto Save periodically protects against loss of data. 409* File Aliases:: Handling multiple names for one file. 410* Version Control:: Version control systems (RCS and SCCS). 411* ListDir:: Listing the contents of a file directory. 412* Comparing Files:: Finding where two files differ. 413* Misc File Ops:: Other things you can do on files. 414 415 416File: emacs, Node: File Names, Next: Visiting, Up: Files 417 418File Names 419========== 420 421 Most Emacs commands that operate on a file require you to specify the 422file name. (Saving and reverting are exceptions; the buffer knows which 423file name to use for them.) You enter the file name using the 424minibuffer (*note Minibuffer::.). "Completion" is available, to make 425it easier to specify long file names. *Note Completion::. 426 427 For most operations, there is a "default file name" which is used if 428you type just RET to enter an empty argument. Normally the default 429file name is the name of the file visited in the current buffer; this 430makes it easy to operate on that file with any of the Emacs file 431commands. 432 433 Each buffer has a default directory, normally the same as the 434directory of the file visited in that buffer. When you enter a file 435name without a directory, the default directory is used. If you specify 436a directory in a relative fashion, with a name that does not start with 437a slash, it is interpreted with respect to the default directory. The 438default directory is kept in the variable `default-directory', which 439has a separate value in every buffer. 440 441 For example, if the default file name is `/u/rms/gnu/gnu.tasks' then 442the default directory is `/u/rms/gnu/'. If you type just `foo', which 443does not specify a directory, it is short for `/u/rms/gnu/foo'. 444`../.login' would stand for `/u/rms/.login'. `new/foo' would stand for 445the file name `/u/rms/gnu/new/foo'. 446 447 The command `M-x pwd' prints the current buffer's default directory, 448and the command `M-x cd' sets it (to a value read using the 449minibuffer). A buffer's default directory changes only when the `cd' 450command is used. A file-visiting buffer's default directory is 451initialized to the directory of the file that is visited there. If you 452create a buffer with `C-x b', its default directory is copied from that 453of the buffer that was current at the time. 454 455 The default directory actually appears in the minibuffer when the 456minibuffer becomes active to read a file name. This serves two 457purposes: it *shows* you what the default is, so that you can type a 458relative file name and know with certainty what it will mean, and it 459allows you to *edit* the default to specify a different directory. 460This insertion of the default directory is inhibited if the variable 461`insert-default-directory' is set to `nil'. 462 463 Note that it is legitimate to type an absolute file name after you 464enter the minibuffer, ignoring the presence of the default directory 465name as part of the text. The final minibuffer contents may look 466invalid, but that is not so. For example, if the minibuffer starts out 467with `/usr/tmp/' and you add `/x1/rms/foo', the double slash says to 468ignore the default directory and use just the name that you typed. 469*Note Minibuffer File::. 470 471 You can refer to files on other machines using a special file name 472syntax: 473 474 /HOST:FILENAME 475 /USER@HOST:FILENAME 476 477 When you do this, Emacs uses the FTP program to read and write files 478on the specified host. It logs in through FTP using your user name or 479the name USER. It may ask you for a password from time to time; this 480is used for logging in on HOST. 481 482 `$' in a file name is used to substitute environment variables. For 483example, if you have used the shell command `setenv FOO rms/hacks' to 484set up an environment variable named `FOO', then you can use 485`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for 486`/u/rms/hacks/test.c'. The environment variable name consists of all 487the alphanumeric characters after the `$'; alternatively, it may be 488enclosed in braces after the `$'. Note that the `setenv' command 489affects Emacs only if done before Emacs is started. 490 491 To access a file with `$' in its name, type `$$'. This pair is 492converted to a single `$' at the same time as variable substitution is 493performed for single `$'. The Lisp function that performs the 494substitution is called `substitute-in-file-name'. The substitution is 495performed only on file names read as such using the minibuffer. 496 497 498File: emacs, Node: Visiting, Next: Saving, Prev: File Names, Up: Files 499 500Visiting Files 501============== 502 503`C-x C-f' 504 Visit a file (`find-file'). 505 506`C-x C-r' 507 Visit a file for viewing, without allowing changes to it 508 (`find-file-read-only'). 509 510`C-x C-v' 511 Visit a different file instead of the one visited last 512 (`find-alternate-file'). 513 514`C-x 4 C-f' 515 Visit a file, in another window (`find-file-other-window'). Don't 516 change the selected window. 517 518`C-x 5 C-f' 519 Visit a file, in a new frame (`find-file-other-frame'). Don't 520 change the selected frame. 521 522 "Visiting" a file means copying its contents into an Emacs buffer so 523you can edit them. Emacs makes a new buffer for each file that you 524visit. We say that this buffer is visiting the file that it was created 525to hold. Emacs constructs the buffer name from the file name by 526throwing away the directory, keeping just the name proper. For example, 527a file named `/usr/rms/emacs.tex' would get a buffer named `emacs.tex'. 528If there is already a buffer with that name, a unique name is 529constructed by appending `<2>', `<3>', or so on, using the lowest 530number that makes a name that is not already in use. 531 532 Each window's mode line shows the name of the buffer that is being 533displayed in that window, so you can always tell what buffer you are 534editing. 535 536 The changes you make with Emacs are made in the Emacs buffer. They 537do not take effect in the file that you visited, or any place 538permanent, until you "save" the buffer. Saving the buffer means that 539Emacs writes the current contents of the buffer into its visited file. 540*Note Saving::. 541 542 If a buffer contains changes that have not been saved, we say the 543buffer is "modified". This is important because it implies that some 544changes will be lost if the buffer is not saved. The mode line 545displays two stars near the left margin to indicate that the buffer is 546modified. 547 548 To visit a file, use the command `C-x C-f' (`find-file'). Follow 549the command with the name of the file you wish to visit, terminated by a 550RET. 551 552 The file name is read using the minibuffer (*note Minibuffer::.), 553with defaulting and completion in the standard manner (*note File 554Names::.). While in the minibuffer, you can abort `C-x C-f' by typing 555`C-g'. 556 557 Your confirmation that `C-x C-f' has completed successfully is the 558appearance of new text on the screen and a new buffer name in the mode 559line. If the specified file does not exist and could not be created, or 560cannot be read, then you get an error, with an error message displayed 561in the echo area. 562 563 If you visit a file that is already in Emacs, `C-x C-f' does not make 564another copy. It selects the existing buffer containing that file. 565However, before doing so, it checks that the file itself has not changed 566since you visited or saved it last. If the file has changed, a warning 567message is printed. *Note Simultaneous Editing: Interlocking. 568 569 What if you want to create a new file? Just visit it. Emacs prints 570`(New File)' in the echo area, but in other respects behaves as if you 571had visited an existing empty file. If you make any changes and save 572them, the file is created. 573 574 If the file you specify is actually a directory, Dired is called on 575that directory (*note Dired::.). This can be inhibited by setting the 576variable `find-file-run-dired' to `nil'; then it is an error to try to 577visit a directory. 578 579 If you visit a file that the operating system won't let you modify, 580Emacs makes the buffer read-only, so that you won't go ahead and make 581changes that you'll have trouble saving afterward. You can make the 582buffer writable with `C-x C-q' (`vc-toggle-read-only'). *Note Misc 583Buffer::. 584 585 Occasionally you might want to visit a file as read-only in order to 586protect yourself from entering changes accidentally; do so by visiting 587the file with the command `C-x C-r' (`find-file-read-only'). 588 589 If you visit a nonexistent file unintentionally (because you typed 590the wrong file name), use the `C-x C-v' command (`find-alternate-file') 591to visit the file you really wanted. `C-x C-v' is similar to `C-x 592C-f', but it kills the current buffer (after first offering to save it 593if it is modified). When it reads the file name to visit, it inserts 594the entire default file name in the buffer, with point just after the 595directory part; this is convenient if you made a slight error in typing 596the name. 597 598 `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that 599the buffer containing the specified file is selected in another window. 600The window that was selected before `C-x 4 f' continues to show the 601same buffer it was already showing. If this command is used when only 602one window is being displayed, that window is split in two, with one 603window showing the same buffer as before, and the other one showing the 604newly requested file. *Note Windows::. 605 606 `C-x 5 f' (`find-file-other-frame') is similar, but opens a new 607frame. This feature is available only when you are using a window 608system. *Note Frames::. 609 610 Two special hook variables allow extensions to modify the operation 611of visiting files. Visiting a file that does not exist runs the 612functions in the list `find-file-not-found-hooks'; this variable holds 613a list of functions, and the functions are called one by one until one 614of them returns non-`nil'. Any visiting of a file, whether extant or 615not, expects `find-file-hooks' to contain a list of functions and calls 616them all, one by one. In both cases the functions receive no 617arguments. Of these two variables, `find-file-not-found-hooks' takes 618effect first. These variables are *not* normal hooks, and their names 619end in `-hooks' rather than `-hook' to indicate that fact. 620 621 There are several ways to specify automatically the major mode for 622editing the file (*note Choosing Modes::.), and to specify local 623variables defined for that file (*note File Variables::.). 624 625 626File: emacs, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files 627 628Saving Files 629============ 630 631 "Saving" a buffer in Emacs means writing its contents back into the 632file that was visited in the buffer. 633 634`C-x C-s' 635 Save the current buffer in its visited file (`save-buffer'). 636 637`C-x s' 638 Save any or all buffers in their visited files 639 (`save-some-buffers'). 640 641`M-~' 642 Forget that the current buffer has been changed (`not-modified'). 643 644`C-x C-w' 645 Save the current buffer in a specified file (`write-file'). 646 647`M-x set-visited-file-name' 648 Change file the name under which the current buffer will be saved. 649 650 When you wish to save the file and make your changes permanent, type 651`C-x C-s' (`save-buffer'). After saving is finished, `C-x C-s' prints 652a message such as 653 654 Wrote /u/rms/gnu/gnu.tasks 655 656If the selected buffer is not modified (no changes have been made in it 657since the buffer was created or last saved), saving is not really done, 658because it would have no effect. Instead, `C-x C-s' prints a message 659in the echo area saying 660 661 (No changes need to be written) 662 663 The command `C-x s' (`save-some-buffers') offers to save any or all 664modified buffers. It asks you what to do with each buffer. The 665options are analogous to those of `query-replace': 666 667`y' 668 Save this buffer and ask about the rest of the buffers. 669 670`n' 671 Don't save this buffer, but ask about the rest of the buffers. 672 673`!' 674 Save this buffer and all the rest with no more questions. 675 676`ESC' 677 Terminate `save-some-buffers' without any more saving. 678 679`.' 680 Save this buffer, then exit `save-some-buffers' without even asking 681 about other buffers. 682 683`C-r' 684 View the buffer that you are currently being asked about. When 685 you exit View mode, you get back to `save-some-buffers', which 686 asks the question again. 687 688`C-h' 689 Display a help message about these options. 690 691 `C-x C-c', the key sequence to exit Emacs, invokes 692`save-some-buffers' and therefore asks the same questions. 693 694 If you have changed a buffer and do not want the changes to be saved, 695you should take some action to prevent it. Otherwise, each time you use 696`C-x s' or `C-x C-c', you are liable to save it by mistake. One thing 697you can do is type `M-~' (`not-modified'), which clears out the 698indication that the buffer is modified. If you do this, none of the 699save commands will believe that the buffer needs to be saved. (`~' is 700often used as a mathematical symbol for `not'; thus `M-~' is `not', 701metafied.) You could also use `set-visited-file-name' (see below) to 702mark the buffer as visiting a different file name, one which is not in 703use for anything important. Alternatively, you can cancel all the 704changes made since the file was visited or saved, by reading the text 705from the file again. This is called "reverting". *Note Reverting::. 706You could also undo all the changes by repeating the undo command `C-x 707u' until you have undone all the changes; but reverting is easier. 708 709 `M-x set-visited-file-name' alters the name of the file that the 710current buffer is visiting. It reads the new file name using the 711minibuffer. Then it specifies the visited file name and changes the 712buffer name correspondingly (as long as the new name is not in use). 713`set-visited-file-name' does not save the buffer in the newly visited 714file; it just alters the records inside Emacs in case you do save 715later. It also marks the buffer as "modified" so that `C-x C-s' in 716that buffer *will* save. 717 718 If you wish to mark the buffer as visiting a different file and save 719it right away, use `C-x C-w' (`write-file'). It is precisely 720equivalent to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' 721used on a buffer that is not visiting with a file has the same effect 722as `C-x C-w'; that is, it reads a file name, marks the buffer as 723visiting that file, and saves it there. The default file name in a 724buffer that is not visiting a file is made by combining the buffer name 725with the buffer's default directory. 726 727 If Emacs is about to save a file and sees that the date of the latest 728version on disk does not match what Emacs last read or wrote, Emacs 729notifies you of this fact, because it probably indicates a problem 730caused by simultaneous editing and requires your immediate attention. 731*Note Simultaneous Editing: Interlocking. 732 733 If the variable `require-final-newline' is non-`nil', Emacs puts a 734newline at the end of any file that doesn't already end in one, every 735time a file is saved or written. 736 737 You can implement other ways to write files, and other things to be 738done before writing them, using the variable `write-file-hooks'. The 739value of this variable should be a list of Lisp functions. When a file 740is to be written, the functions in the list are called, one by one, 741with no arguments. If one of them returns a non-`nil' value, Emacs 742takes this to mean that the file has been written in some suitable 743fashion; the rest of the functions are not called, and normal writing 744is not done. If this variable is local to a buffer, changing major 745modes does not clear it. However, changing the visited file name does 746clear this variable to `nil'. 747 748 The list `local-write-file-hooks' is used just like 749`write-file-hooks'. This list is for use as a local variable. It is a 750permanent local, so that switching major modes does not affect it. 751 752 The variable `write-contents-hooks' holds another list of functions 753to be called before writing out a buffer to a file. These functions 754are used just like the ones in `write-file-hooks'. The difference 755between this and `write-file-hooks' is that changing the major mode 756does clear this variable, and setting the visited file name does not 757clear it. 758 759 The hook functions are responsible for writing backup files, if you 760want that to be done. Here is how: 761 762 (or buffer-backed-up (backup-buffer)) 763 764You might also wish to save the file modes value returned by 765`backup-buffer' and use that to set the mode bits of the file that you 766write. This is what happens ordinarily when backups are made. 767 768 The hook variables described here are not normal hooks, because the 769values returned by the hook functions do matter. This is why they have 770names ending in `-hooks' rather than `-hook'. *Note Hooks::. 771 772* Menu: 773 774* Backup:: How Emacs saves the old version of your file. 775* Interlocking:: How Emacs protects against simultaneous editing 776 of one file by two users. 777 778 779File: emacs, Node: Backup, Next: Interlocking, Up: Saving 780 781Backup Files 782------------ 783 784 Because Unix does not provide version numbers in file names, 785rewriting a file in Unix automatically destroys all record of what the 786file used to contain. Thus, saving a file from Emacs throws away the 787old contents of the file--or it would, except that Emacs carefully 788copies the old contents to another file, called the "backup" file, 789before actually saving. (This assumes that the variable 790`make-backup-files' is non-`nil'. Backup files are not written if this 791variable is `nil'.) 792 793 At your option, Emacs can keep either a single backup file or a 794series of numbered backup files for each file that you edit. 795 796 Emacs makes a backup for a file only the first time the file is saved 797from one buffer. No matter how many times you save a file, its backup 798file continues to contain the contents from before the file was visited. 799Normally this means that the backup file contains the contents from 800before the current editing session; however, if you kill the buffer and 801then visit the file again, a new backup file will be made by the next 802save. 803 804* Menu: 805 806* Names: Backup Names. How backup files are named; 807 choosing single or numbered backup files. 808* Deletion: Backup Deletion. Emacs deletes excess numbered backups. 809* Copying: Backup Copying. Backups can be made by copying or renaming. 810 811 812File: emacs, Node: Backup Names, Next: Backup Deletion, Up: Backup 813 814Single or Numbered Backups 815.......................... 816 817 If you choose to have a single backup file (this is the default), 818the backup file's name is constructed by appending `~' to the file name 819being edited; thus, the backup file for `eval.c' would be `eval.c~'. 820 821 If you choose to have a series of numbered backup files, backup file 822names are made by appending `.~', the number, and another `~' to the 823original file name. Thus, the backup files of `eval.c' would be called 824`eval.c.~1~', `eval.c.~2~', and so on, through names like 825`eval.c.~259~' and beyond. 826 827 If protection stops you from writing backup files under the usual 828names, the backup file is written as `%backup%~' in your home directory. 829Only one such file can exist, so only the most recently made such 830backup is available. 831 832 The choice of single backup or numbered backups is controlled by the 833variable `version-control'. Its possible values are 834 835`t' 836 Make numbered backups. 837 838`nil' 839 Make numbered backups for files that have numbered backups already. 840 Otherwise, make single backups. 841 842`never' 843 Do not in any case make numbered backups; always make single 844 backups. 845 846You can set `version-control' locally in an individual buffer to 847control the making of backups for that buffer's file. For example, 848Rmail mode locally sets `version-control' to `never' to make sure that 849there is only one backup for an Rmail file. *Note Locals::. 850 851 If you set the environment variable `VERSION_CONTROL', to tell 852various GNU utilities what to do with backup files, Emacs also obeys the 853environment variable by setting the Lisp variable `version-control' 854accordingly at startup. If the environment variable's value is `t' or 855`numbered', then `version-control' becomes `t'; if the value is `nil' 856or `existing', then `version-control' becomes `nil'; if it is `never' 857or `simple', then `version-control' becomes `never'. 858 859 For files under version control (*note Version Control::.), the 860variable `vc-make-backup-files' determines whether to make backup 861files. By default, it is `nil', since backup files are redundant when 862you store all the previous versions in a version control system. *Note 863Editing with VC::. 864 865 866File: emacs, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup 867 868Automatic Deletion of Backups 869............................. 870 871 To prevent unlimited consumption of disk space, Emacs can delete 872numbered backup versions automatically. Generally Emacs keeps the 873first few backups and the latest few backups, deleting any in between. 874This happens every time a new backup is made. 875 876 The two variables `kept-old-versions' and `kept-new-versions' 877control this deletion. Their values are, respectively the number of 878oldest (lowest-numbered) backups to keep and the number of newest 879(highest-numbered) ones to keep, each time a new backup is made. 880Recall that these values are used just after a new backup version is 881made; that newly made backup is included in the count in 882`kept-new-versions'. By default, both variables are 2. 883 884 If `trim-versions-without-asking' is non-`nil', the excess middle 885versions are deleted without a murmur. If it is `nil', the default, 886then you are asked whether the excess middle versions should really be 887deleted. 888 889 Dired's `.' (Period) command can also be used to delete old versions. 890*Note Dired Deletion::. 891 892 893File: emacs, Node: Backup Copying, Prev: Backup Deletion, Up: Backup 894 895Copying vs. Renaming 896.................... 897 898 Backup files can be made by copying the old file or by renaming it. 899This makes a difference when the old file has multiple names. If the 900old file is renamed into the backup file, then the alternate names 901become names for the backup file. If the old file is copied instead, 902then the alternate names remain names for the file that you are 903editing, and the contents accessed by those names will be the new 904contents. 905 906 The method of making a backup file may also affect the file's owner 907and group. If copying is used, these do not change. If renaming is 908used, you become the file's owner, and the file's group becomes the 909default (different operating systems have different defaults for the 910group). 911 912 Having the owner change is usually a good idea, because then the 913owner always shows who last edited the file. Also, the owners of the 914backups show who produced those versions. Occasionally there is a file 915whose owner should not change; it is a good idea for such files to 916contain local variable lists to set `backup-by-copying-when-mismatch' 917locally (*note File Variables::.). 918 919 The choice of renaming or copying is controlled by three variables. 920Renaming is the default choice. If the variable `backup-by-copying' is 921non-`nil', copying is used. Otherwise, if the variable 922`backup-by-copying-when-linked' is non-`nil', then copying is used for 923files that have multiple names, but renaming may still used when the 924file being edited has only one name. If the variable 925`backup-by-copying-when-mismatch' is non-`nil', then copying is used if 926renaming would cause the file's owner or group to change. 927 928 929File: emacs, Node: Interlocking, Prev: Backup, Up: Saving 930 931Protection against Simultaneous Editing 932--------------------------------------- 933 934 Simultaneous editing occurs when two users visit the same file, both 935make changes, and then both save them. If nobody were informed that 936this was happening, whichever user saved first would later find that his 937changes were lost. On some systems, Emacs notices immediately when the 938second user starts to change the file, and issues an immediate warning. 939 940 For the sake of systems where that is not possible, and in case 941someone else proceeds to change the file despite the warning, Emacs also 942checks when the file is saved, and issues a second warning if you are 943about to overwrite a file containing another user's changes. You can 944prevent loss of the other user's work by taking the proper corrective 945action at that time. 946 947 When you make the first modification in an Emacs buffer that is 948visiting a file, Emacs records that the file is "locked" by you. (It 949does this by writing another file in a directory reserved for this 950purpose.) The lock is removed when you save the changes. The idea is 951that the file is locked whenever an Emacs buffer visiting it has 952unsaved changes. 953 954 If you begin to modify the buffer while the visited file is locked by 955someone else, this constitutes a "collision". When Emacs detects a 956collision, it asks you what to do, by calling the Lisp function 957`ask-user-about-lock'. You can redefine this function for the sake of 958customization. The standard definition of this function asks you a 959question and accepts three possible answers: 960 961`s' 962 Steal the lock. Whoever was already changing the file loses the 963 lock, and you gain the lock. 964 965`p' 966 Proceed. Go ahead and edit the file despite its being locked by 967 someone else. 968 969`q' 970 Quit. This causes an error (`file-locked') and the modification 971 you were trying to make in the buffer does not actually take place. 972 973 Note that locking works on the basis of a file name; if a file has 974multiple names, Emacs does not realize that the two names are the same 975file and cannot prevent two users from editing it simultaneously under 976different names. However, basing locking on names means that Emacs can 977interlock the editing of new files that will not really exist until 978they are saved. 979 980 Some systems are not configured to allow Emacs to make locks. On 981these systems, Emacs cannot detect trouble in advance, but it still can 982detect the collision when you try to save a file and overwrite someone 983else's changes. 984 985 Every time Emacs saves a buffer, it first checks the 986last-modification date of the existing file on disk to verify that it 987has not changed since the file was last visited or saved. If the date 988does not match, it implies that changes were made in the file in some 989other way, and these changes are about to be lost if Emacs actually 990does save. To prevent this, Emacs prints a warning message and asks 991for confirmation before saving. Occasionally you will know why the 992file was changed and know that it does not matter; then you can answer 993`yes' and proceed. Otherwise, you should cancel the save with `C-g' 994and investigate the situation. 995 996 The first thing you should do when notified that simultaneous 997editing has already taken place is to list the directory with `C-u C-x 998C-d' (*note Directory Listing: ListDir.). This shows the file's 999current author. You should attempt to contact him to warn him not to 1000continue editing. Often the next step is to save the contents of your 1001Emacs buffer under a different name, and use `diff' to compare the two 1002files. 1003 1004 Simultaneous editing checks are also made when you visit with `C-x 1005C-f' a file that is already visited and when you start to modify a 1006file. This is not strictly necessary, but it can cause you to find out 1007about the collision earlier, when perhaps correction takes less work. 1008 1009 1010File: emacs, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files 1011 1012Reverting a Buffer 1013================== 1014 1015 If you have made extensive changes to a file and then change your 1016mind about them, you can get rid of them by reading in the previous 1017version of the file. To do this, use `M-x revert-buffer', which 1018operates on the current buffer. Since this is a very dangerous thing 1019to do, you must confirm it with `yes'. 1020 1021 `revert-buffer' keeps point at the same distance (measured in 1022characters) from the beginning of the file. If the file was edited only 1023slightly, you will be at approximately the same piece of text after 1024reverting as before. If you have made drastic changes, the same value 1025of point in the old file may address a totally different piece of text. 1026 1027 Reverting marks the buffer as "not modified" until another change is 1028made. 1029 1030 Some kinds of buffers whose contents reflect data bases other than 1031files, such as Dired buffers, can also be reverted. For them, 1032reverting means recalculating their contents from the appropriate data 1033base. Buffers created randomly with `C-x b' cannot be reverted; 1034`revert-buffer' reports an error when asked to do so. 1035 1036 1037File: emacs, Node: Auto Save, Next: File Aliases, Prev: Reverting, Up: Files 1038 1039Auto-Saving: Protection Against Disasters 1040========================================= 1041 1042 Emacs saves all the visited files from time to time (based on 1043counting your keystrokes) without being asked. This is called 1044"auto-saving". It prevents you from losing more than a limited amount 1045of work if the system crashes. 1046 1047 When Emacs determines that it is time for auto-saving, each buffer is 1048considered, and is auto-saved if auto-saving is turned on for it and it 1049has been changed since the last time it was auto-saved. If any 1050auto-saving is done, the message `Auto-saving...' is displayed in the 1051echo area until auto-saving is finished. Errors occurring during 1052auto-saving are caught so that they do not interfere with the execution 1053of commands you have been typing. 1054 1055* Menu: 1056 1057* Files: Auto Save Files. The file where auto-saved changes are 1058 actually made until you save the file. 1059* Control: Auto Save Control. Controlling when and how often to auto-save. 1060* Recover:: Recovering text from auto-save files. 1061 1062 1063File: emacs, Node: Auto Save Files, Next: Auto Save Control, Up: Auto Save 1064 1065Auto-Save Files 1066--------------- 1067 1068 Auto-saving does not normally save in the files that you visited, 1069because it can be very undesirable to save a program that is in an 1070inconsistent state when you have made half of a planned change. 1071Instead, auto-saving is done in a different file called the "auto-save 1072file", and the visited file is changed only when you request saving 1073explicitly (such as with `C-x C-s'). 1074 1075 Normally, the auto-save file name is made by appending `#' to the 1076front and rear of the visited file name. Thus, a buffer visiting file 1077`foo.c' is auto-saved in a file `#foo.c#'. Most buffers that are not 1078visiting files are auto-saved only if you request it explicitly; when 1079they are auto-saved, the auto-save file name is made by appending `#%' 1080to the front and `#' to the rear of buffer name. For example, the 1081`*mail*' buffer in which you compose messages to be sent is auto-saved 1082in a file named `#%*mail*#'. Auto-save file names are made this way 1083unless you reprogram parts of Emacs to do something different (the 1084functions `make-auto-save-file-name' and `auto-save-file-name-p'). The 1085file name to be used for auto-saving in a buffer is calculated when 1086auto-saving is turned on in that buffer. 1087 1088 When you delete a substantial part of the text in a large buffer, 1089auto save turns off temporarily in that buffer. This is so that if you 1090delete text accidentally, it is likely to remain present in the auto 1091save file. To reenable auto-saving after this happens, simply save the 1092file explicitly with `C-x C-s'. Using `C-u 1 M-x auto-save-mode' also 1093cancels this particular state. 1094 1095 If you want auto-saving to be done in the visited file, set the 1096variable `auto-save-visited-file-name' to be non-`nil'. In this mode, 1097there is really no difference between auto-saving and explicit saving. 1098 1099 A buffer's auto-save file is deleted when you save the buffer in its 1100visited file. To inhibit this, set the variable 1101`delete-auto-save-files' to `nil'. Changing the visited file name with 1102`C-x C-w' or `set-visited-file-name' renames any auto-save file to go 1103with the new visited name. 1104 1105 When you delete a large amount of a buffer's text, auto-saving turns 1106off in that buffer. This is because if you deleted the text 1107unintentionally, you might find the auto-save file more useful if it 1108contains the deleted text. To restart auto-saving in that buffer, use 1109`M-x auto-save' with a positive argument. 1110 1111 1112File: emacs, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save 1113 1114Controlling Auto-Saving 1115----------------------- 1116 1117 Each time you visit a file, auto-saving is turned on for that file's 1118buffer if the variable `auto-save-default' is non-`nil' (but not in 1119batch mode; *note Entering Emacs::.). The default for this variable is 1120`t', so auto-saving is the usual practice for file-visiting buffers. 1121Auto-saving can be turned on or off for any existing buffer with the 1122command `M-x auto-save-mode'. Like other minor mode commands, `M-x 1123auto-save-mode' turns auto-saving on with a positive argument, off with 1124a zero or negative argument; with no argument, it toggles. 1125 1126 Emacs does auto-saving periodically based on counting how many 1127characters you have typed since the last time auto-saving was done. 1128The variable `auto-save-interval' specifies how many characters there 1129are between auto-saves. By default, it is 300. 1130 1131 Auto-saving also takes place when you stop typing for a while. The 1132variable `auto-save-timeout' says how many seconds Emacs should wait 1133before it does an auto save (and perhaps also a garbage collection). 1134(The actual time period is longer if the current buffer is long; this 1135is a heuristic which aims to keep out of your way when you are editing 1136long buffers in which auto-save takes an appreciable amount of time.) 1137Auto-saving during idle periods accomplishes two things: first, it 1138makes sure all your work is saved if you go away from the terminal for 1139a while; second, it may avoid some auto-saving while you are actually 1140typing. 1141 1142 Emacs also does auto-saving whenever it gets a fatal error. This 1143includes killing the Emacs job with a shell command such as `kill 1144%emacs', or disconnecting a phone line or network connection. 1145 1146 You can request an auto-save explicitly with the command `M-x 1147do-auto-save'. 1148 1149