| 1 | @c This is part of the Emacs manual. |
| 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 |
| 3 | @c Free Software Foundation, Inc. |
| 4 | @c See file emacs.texi for copying conditions. |
| 5 | @node Files |
| 6 | @chapter File Handling |
| 7 | @cindex files |
| 8 | |
| 9 | The operating system stores data permanently in named @dfn{files}, so |
| 10 | most of the text you edit with Emacs comes from a file and is ultimately |
| 11 | stored in a file. |
| 12 | |
| 13 | To edit a file, you must tell Emacs to read the file and prepare a |
| 14 | buffer containing a copy of the file's text. This is called |
| 15 | @dfn{visiting} the file. Editing commands apply directly to text in the |
| 16 | buffer; that is, to the copy inside Emacs. Your changes appear in the |
| 17 | file itself only when you @dfn{save} the buffer back into the file. |
| 18 | |
| 19 | In addition to visiting and saving files, Emacs can delete, copy, |
| 20 | rename, and append to files, keep multiple versions of them, and operate |
| 21 | on file directories. |
| 22 | |
| 23 | @menu |
| 24 | * File Names:: How to type and edit file-name arguments. |
| 25 | * Visiting:: Visiting a file prepares Emacs to edit the file. |
| 26 | * Saving:: Saving makes your changes permanent. |
| 27 | * Reverting:: Reverting cancels all the changes not saved. |
| 28 | @ifnottex |
| 29 | * Autorevert:: Auto Reverting non-file buffers. |
| 30 | @end ifnottex |
| 31 | * Auto Save:: Auto Save periodically protects against loss of data. |
| 32 | * File Aliases:: Handling multiple names for one file. |
| 33 | * Directories:: Creating, deleting, and listing file directories. |
| 34 | * Comparing Files:: Finding where two files differ. |
| 35 | * Diff Mode:: Mode for editing file differences. |
| 36 | * Misc File Ops:: Other things you can do on files. |
| 37 | * Compressed Files:: Accessing compressed files. |
| 38 | * File Archives:: Operating on tar, zip, jar etc. archive files. |
| 39 | * Remote Files:: Accessing files on other machines. |
| 40 | * Quoted File Names:: Quoting special characters in file names. |
| 41 | * File Name Cache:: Completion against a list of files you often use. |
| 42 | * File Conveniences:: Convenience Features for Finding Files. |
| 43 | * Filesets:: Handling sets of files. |
| 44 | @end menu |
| 45 | |
| 46 | @node File Names |
| 47 | @section File Names |
| 48 | @cindex file names |
| 49 | |
| 50 | @cindex default file name |
| 51 | Many Emacs commands that operate on a file require you to specify |
| 52 | the file name, using the minibuffer (@pxref{Minibuffer File}). |
| 53 | |
| 54 | While in the minibuffer, you can use the usual completion and |
| 55 | history commands (@pxref{Minibuffer}). Note that file name completion |
| 56 | ignores file names whose extensions appear in the variable |
| 57 | @code{completion-ignored-extensions} (@pxref{Completion Options}). |
| 58 | Note also that most commands use ``permissive completion with |
| 59 | confirmation'' for reading file names: you are allowed to submit a |
| 60 | nonexistent file name, but if you type @key{RET} immediately after |
| 61 | completing up to a nonexistent file name, Emacs prints |
| 62 | @samp{[Confirm]} and you must type a second @key{RET} to confirm. |
| 63 | @xref{Completion Exit}, for details. |
| 64 | |
| 65 | @cindex default directory |
| 66 | @vindex default-directory |
| 67 | @vindex insert-default-directory |
| 68 | Each buffer has a @dfn{default directory}, stored in the |
| 69 | buffer-local variable @code{default-directory}. Whenever Emacs reads |
| 70 | a file name using the minibuffer, it usually inserts the default |
| 71 | directory into the minibuffer as the initial contents. You can |
| 72 | inhibit this insertion by changing the variable |
| 73 | @code{insert-default-directory} to @code{nil} (@pxref{Minibuffer |
| 74 | File}). Regardless, Emacs always assumes that any relative file name |
| 75 | is relative to the default directory, e.g. entering a file name |
| 76 | without a directory specifies a file in the default directory. |
| 77 | |
| 78 | @findex cd |
| 79 | @findex pwd |
| 80 | When you visit a file, Emacs sets @code{default-directory} in the |
| 81 | visiting buffer to the directory of its file. When you create a new |
| 82 | buffer that is not visiting a file, via a command like @kbd{C-x b}, |
| 83 | its default directory is usually copied from the buffer that was |
| 84 | current at the time (@pxref{Select Buffer}). You can use the command |
| 85 | @kbd{M-x pwd} to see the value of @code{default-directory} in the |
| 86 | current buffer. The command @kbd{M-x cd} prompts for a directory |
| 87 | name, and sets the buffer's @code{default-directory} to that directory |
| 88 | (doing this does not change the buffer's file name, if any). |
| 89 | |
| 90 | As an example, when you visit the file @file{/u/rms/gnu/gnu.tasks}, |
| 91 | the default directory is set to @file{/u/rms/gnu/}. If you invoke a |
| 92 | command that reads a file name, entering just @samp{foo} in the |
| 93 | minibuffer, with a directory omitted, specifies the file |
| 94 | @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies |
| 95 | @file{/u/rms/.login}; and entering @samp{new/foo} specifies |
| 96 | @file{/u/rms/gnu/new/foo}. |
| 97 | |
| 98 | When typing a file name into the minibuffer, you can make use of a |
| 99 | couple of shortcuts: a double slash is interpreted as ``ignore |
| 100 | everything before the second slash in the pair'', and @samp{~/} is |
| 101 | interpreted as your home directory. @xref{Minibuffer File}. |
| 102 | |
| 103 | @cindex environment variables in file names |
| 104 | @cindex expansion of environment variables |
| 105 | @cindex @code{$} in file names |
| 106 | @anchor{File Names with $}The character @samp{$} is used to |
| 107 | substitute an environment variable into a file name. The name of the |
| 108 | environment variable consists of all the alphanumeric characters after |
| 109 | the @samp{$}; alternatively, it can be enclosed in braces after the |
| 110 | @samp{$}. For example, if you have used the shell command |
| 111 | @command{export FOO=rms/hacks} to set up an environment variable named |
| 112 | @env{FOO}, then both @file{/u/$FOO/test.c} and |
| 113 | @file{/u/$@{FOO@}/test.c} are abbreviations for |
| 114 | @file{/u/rms/hacks/test.c}. If the environment variable is not |
| 115 | defined, no substitution occurs, so that the character @samp{$} stands |
| 116 | for itself. Note that environment variables affect Emacs only if they |
| 117 | are applied before Emacs is started. |
| 118 | |
| 119 | To access a file with @samp{$} in its name, if the @samp{$} causes |
| 120 | expansion, type @samp{$$}. This pair is converted to a single |
| 121 | @samp{$} at the same time that variable substitution is performed for |
| 122 | a single @samp{$}. Alternatively, quote the whole file name with |
| 123 | @samp{/:} (@pxref{Quoted File Names}). File names which begin with a |
| 124 | literal @samp{~} should also be quoted with @samp{/:}. |
| 125 | |
| 126 | You can include non-@acronym{ASCII} characters in file names. |
| 127 | @xref{File Name Coding}. |
| 128 | |
| 129 | @node Visiting |
| 130 | @section Visiting Files |
| 131 | @cindex visiting files |
| 132 | @cindex open file |
| 133 | |
| 134 | @table @kbd |
| 135 | @item C-x C-f |
| 136 | Visit a file (@code{find-file}). |
| 137 | @item C-x C-r |
| 138 | Visit a file for viewing, without allowing changes to it |
| 139 | (@code{find-file-read-only}). |
| 140 | @item C-x C-v |
| 141 | Visit a different file instead of the one visited last |
| 142 | (@code{find-alternate-file}). |
| 143 | @item C-x 4 f |
| 144 | Visit a file, in another window (@code{find-file-other-window}). Don't |
| 145 | alter what is displayed in the selected window. |
| 146 | @item C-x 5 f |
| 147 | Visit a file, in a new frame (@code{find-file-other-frame}). Don't |
| 148 | alter what is displayed in the selected frame. |
| 149 | @item M-x find-file-literally |
| 150 | Visit a file with no conversion of the contents. |
| 151 | @end table |
| 152 | |
| 153 | @cindex files, visiting and saving |
| 154 | @cindex saving files |
| 155 | @dfn{Visiting} a file means reading its contents into an Emacs |
| 156 | buffer so you can edit them. Emacs makes a new buffer for each file |
| 157 | that you visit. |
| 158 | |
| 159 | @kindex C-x C-f |
| 160 | @findex find-file |
| 161 | To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the |
| 162 | minibuffer to enter the name of the desired file. While in the |
| 163 | minibuffer, you can abort the command by typing @kbd{C-g}. @xref{File |
| 164 | Names}, for details about entering file names into minibuffers. |
| 165 | |
| 166 | If the specified file exists but the system does not allow you to |
| 167 | read it, an error message is displayed in the echo area. Otherwise, |
| 168 | you can tell that @kbd{C-x C-f} has completed successfully by the |
| 169 | appearance of new text on the screen, and by the buffer name shown in |
| 170 | the mode line (@pxref{Mode Line}). Emacs normally constructs the |
| 171 | buffer name from the file name, omitting the directory name. For |
| 172 | example, a file named @file{/usr/rms/emacs.tex} is visited in a buffer |
| 173 | named @samp{emacs.tex}. If there is already a buffer with that name, |
| 174 | Emacs constructs a unique name; the normal method is to append |
| 175 | @samp{<2>}, @samp{<3>}, and so on, but you can select other methods. |
| 176 | @xref{Uniquify}. |
| 177 | |
| 178 | @cindex creating files |
| 179 | To create a new file, just visit it using the same command, @kbd{C-x |
| 180 | C-f}. Emacs displays @samp{(New file)} in the echo area, but in other |
| 181 | respects behaves as if you had visited an existing empty file. |
| 182 | |
| 183 | @cindex modified (buffer) |
| 184 | After visiting a file, the changes you make with editing commands are |
| 185 | made in the Emacs buffer. They do not take effect in the visited |
| 186 | file, until you @dfn{save} the buffer (@pxref{Saving}). If a buffer |
| 187 | contains changes that have not been saved, we say the buffer is |
| 188 | @dfn{modified}. This implies that some changes will be lost if the |
| 189 | buffer is not saved. The mode line displays two stars near the left |
| 190 | margin to indicate that the buffer is modified. |
| 191 | |
| 192 | If you visit a file that is already in Emacs, @kbd{C-x C-f} switches |
| 193 | to the existing buffer instead of making another copy. Before doing |
| 194 | so, it checks whether the file has changed since you last visited or |
| 195 | saved it. If the file has changed, Emacs offers to reread it. |
| 196 | |
| 197 | @vindex large-file-warning-threshold |
| 198 | @cindex file, warning when size is large |
| 199 | @cindex size of file, warning when visiting |
| 200 | @cindex maximum buffer size exceeded, error message |
| 201 | If you try to visit a file larger than |
| 202 | @code{large-file-warning-threshold} (the default is 10000000, which is |
| 203 | about 10 megabytes), Emacs asks you for confirmation first. You can |
| 204 | answer @kbd{y} to proceed with visiting the file. Note, however, that |
| 205 | Emacs cannot visit files that are larger than the maximum Emacs buffer |
| 206 | size, which is limited by the amount of memory Emacs can allocate and |
| 207 | by the integers that Emacs can represent (@pxref{Buffers}). If you |
| 208 | try, Emacs displays an error message saying that the maximum buffer |
| 209 | size has been exceeded. |
| 210 | |
| 211 | @cindex wildcard characters in file names |
| 212 | @vindex find-file-wildcards |
| 213 | If the file name you specify contains shell-style wildcard |
| 214 | characters, Emacs visits all the files that match it. (On |
| 215 | case-insensitive filesystems, Emacs matches the wildcards disregarding |
| 216 | the letter case.) Wildcards include @samp{?}, @samp{*}, and |
| 217 | @samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file |
| 218 | name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted |
| 219 | File Names}, for information on how to visit a file whose name |
| 220 | actually contains wildcard characters. You can disable the wildcard |
| 221 | feature by customizing @code{find-file-wildcards}. |
| 222 | |
| 223 | @kindex C-x C-v |
| 224 | @findex find-alternate-file |
| 225 | If you visit the wrong file unintentionally by typing its name |
| 226 | incorrectly, type @kbd{C-x C-v} (@code{find-alternate-file}) to visit |
| 227 | the file you really wanted. @kbd{C-x C-v} is similar to @kbd{C-x |
| 228 | C-f}, but it kills the current buffer (after first offering to save it |
| 229 | if it is modified). When @kbd{C-x C-v} reads the file name to visit, |
| 230 | it inserts the entire default file name in the buffer, with point just |
| 231 | after the directory part; this is convenient if you made a slight |
| 232 | error in typing the name. |
| 233 | |
| 234 | @vindex find-file-run-dired |
| 235 | If you ``visit'' a file that is actually a directory, Emacs invokes |
| 236 | Dired, the Emacs directory browser. @xref{Dired}. You can disable |
| 237 | this behavior by setting the variable @code{find-file-run-dired} to |
| 238 | @code{nil}; in that case, it is an error to try to visit a directory. |
| 239 | |
| 240 | Files which are actually collections of other files, or @dfn{file |
| 241 | archives}, are visited in special modes which invoke a Dired-like |
| 242 | environment to allow operations on archive members. @xref{File |
| 243 | Archives}, for more about these features. |
| 244 | |
| 245 | If you visit a file that the operating system won't let you modify, |
| 246 | or that is marked read-only, Emacs makes the buffer read-only too, so |
| 247 | that you won't go ahead and make changes that you'll have trouble |
| 248 | saving afterward. You can make the buffer writable with @kbd{C-x C-q} |
| 249 | (@code{read-only-mode}). @xref{Misc Buffer}. |
| 250 | |
| 251 | @kindex C-x C-r |
| 252 | @findex find-file-read-only |
| 253 | If you want to visit a file as read-only in order to protect |
| 254 | yourself from entering changes accidentally, visit it with the command |
| 255 | @kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. |
| 256 | |
| 257 | @kindex C-x 4 f |
| 258 | @findex find-file-other-window |
| 259 | @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} |
| 260 | except that the buffer containing the specified file is selected in another |
| 261 | window. The window that was selected before @kbd{C-x 4 f} continues to |
| 262 | show the same buffer it was already showing. If this command is used when |
| 263 | only one window is being displayed, that window is split in two, with one |
| 264 | window showing the same buffer as before, and the other one showing the |
| 265 | newly requested file. @xref{Windows}. |
| 266 | |
| 267 | @kindex C-x 5 f |
| 268 | @findex find-file-other-frame |
| 269 | @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a |
| 270 | new frame, or selects any existing frame showing the specified file. |
| 271 | @xref{Frames}. |
| 272 | |
| 273 | @cindex file selection dialog |
| 274 | On graphical displays, there are two additional methods for visiting |
| 275 | files. Firstly, when Emacs is built with a suitable GUI toolkit, |
| 276 | commands invoked with the mouse (by clicking on the menu bar or tool |
| 277 | bar) use the toolkit's standard ``File Selection'' dialog instead of |
| 278 | prompting for the file name in the minibuffer. On GNU/Linux and Unix |
| 279 | platforms, Emacs does this when built with GTK, LessTif, and Motif |
| 280 | toolkits; on MS-Windows and Mac, the GUI version does that by default. |
| 281 | For information on how to customize this, see @ref{Dialog Boxes}. |
| 282 | |
| 283 | Secondly, Emacs supports ``drag and drop'': dropping a file into an |
| 284 | ordinary Emacs window visits the file using that window. As an |
| 285 | exception, dropping a file into a window displaying a Dired buffer |
| 286 | moves or copies the file into the displayed directory. For details, |
| 287 | see @ref{Drag and Drop}, and @ref{Misc Dired Features}. |
| 288 | |
| 289 | Each time you visit a file, Emacs automatically scans its contents |
| 290 | to detect what character encoding and end-of-line convention it uses, |
| 291 | and converts these to Emacs's internal encoding and end-of-line |
| 292 | convention within the buffer. When you save the buffer, Emacs |
| 293 | performs the inverse conversion, writing the file to disk with its |
| 294 | original encoding and end-of-line convention. @xref{Coding Systems}. |
| 295 | |
| 296 | @findex find-file-literally |
| 297 | If you wish to edit a file as a sequence of @acronym{ASCII} |
| 298 | characters with no special encoding or conversion, use the @kbd{M-x |
| 299 | find-file-literally} command. This visits a file, like @kbd{C-x C-f}, |
| 300 | but does not do format conversion (@pxref{Format Conversion,, Format |
| 301 | Conversion, elisp, the Emacs Lisp Reference Manual}), character code |
| 302 | conversion (@pxref{Coding Systems}), or automatic uncompression |
| 303 | (@pxref{Compressed Files}), and does not add a final newline because |
| 304 | of @code{require-final-newline} (@pxref{Customize Save}). If you have |
| 305 | already visited the same file in the usual (non-literal) manner, this |
| 306 | command asks you whether to visit it literally instead. |
| 307 | |
| 308 | @vindex find-file-hook |
| 309 | @vindex find-file-not-found-functions |
| 310 | Two special hook variables allow extensions to modify the operation |
| 311 | of visiting files. Visiting a file that does not exist runs the |
| 312 | functions in @code{find-file-not-found-functions}; this variable holds |
| 313 | a list of functions, which are called one by one (with no arguments) |
| 314 | until one of them returns non-@code{nil}. This is not a normal hook, |
| 315 | and the name ends in @samp{-functions} rather than @samp{-hook} to |
| 316 | indicate that fact. |
| 317 | |
| 318 | Successful visiting of any file, whether existing or not, calls the |
| 319 | functions in @code{find-file-hook}, with no arguments. This variable |
| 320 | is a normal hook. In the case of a nonexistent file, the |
| 321 | @code{find-file-not-found-functions} are run first. @xref{Hooks}. |
| 322 | |
| 323 | There are several ways to specify automatically the major mode for |
| 324 | editing the file (@pxref{Choosing Modes}), and to specify local |
| 325 | variables defined for that file (@pxref{File Variables}). |
| 326 | |
| 327 | @node Saving |
| 328 | @section Saving Files |
| 329 | |
| 330 | @dfn{Saving} a buffer in Emacs means writing its contents back into the file |
| 331 | that was visited in the buffer. |
| 332 | |
| 333 | @menu |
| 334 | * Save Commands:: Commands for saving files. |
| 335 | * Backup:: How Emacs saves the old version of your file. |
| 336 | * Customize Save:: Customizing the saving of files. |
| 337 | * Interlocking:: How Emacs protects against simultaneous editing |
| 338 | of one file by two users. |
| 339 | * Shadowing: File Shadowing. Copying files to "shadows" automatically. |
| 340 | * Time Stamps:: Emacs can update time stamps on saved files. |
| 341 | @end menu |
| 342 | |
| 343 | @node Save Commands |
| 344 | @subsection Commands for Saving Files |
| 345 | |
| 346 | These are the commands that relate to saving and writing files. |
| 347 | |
| 348 | @table @kbd |
| 349 | @item C-x C-s |
| 350 | Save the current buffer to its file (@code{save-buffer}). |
| 351 | @item C-x s |
| 352 | Save any or all buffers to their files (@code{save-some-buffers}). |
| 353 | @item M-~ |
| 354 | Forget that the current buffer has been changed (@code{not-modified}). |
| 355 | With prefix argument (@kbd{C-u}), mark the current buffer as changed. |
| 356 | @item C-x C-w |
| 357 | Save the current buffer with a specified file name (@code{write-file}). |
| 358 | @item M-x set-visited-file-name |
| 359 | Change the file name under which the current buffer will be saved. |
| 360 | @end table |
| 361 | |
| 362 | @kindex C-x C-s |
| 363 | @findex save-buffer |
| 364 | When you wish to save the file and make your changes permanent, type |
| 365 | @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} |
| 366 | displays a message like this: |
| 367 | |
| 368 | @example |
| 369 | Wrote /u/rms/gnu/gnu.tasks |
| 370 | @end example |
| 371 | |
| 372 | @noindent |
| 373 | If the current buffer is not modified (no changes have been made in it |
| 374 | since the buffer was created or last saved), saving is not really |
| 375 | done, because it would have no effect. Instead, @kbd{C-x C-s} |
| 376 | displays a message like this in the echo area: |
| 377 | |
| 378 | @example |
| 379 | (No changes need to be saved) |
| 380 | @end example |
| 381 | |
| 382 | With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer |
| 383 | to be backed up when the next save is done. @xref{Backup}. |
| 384 | |
| 385 | @kindex C-x s |
| 386 | @findex save-some-buffers |
| 387 | The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any |
| 388 | or all modified buffers. It asks you what to do with each buffer. The |
| 389 | possible responses are analogous to those of @code{query-replace}: |
| 390 | |
| 391 | @table @kbd |
| 392 | @item y |
| 393 | Save this buffer and ask about the rest of the buffers. |
| 394 | @item n |
| 395 | Don't save this buffer, but ask about the rest of the buffers. |
| 396 | @item ! |
| 397 | Save this buffer and all the rest with no more questions. |
| 398 | @c following generates acceptable underfull hbox |
| 399 | @item @key{RET} |
| 400 | Terminate @code{save-some-buffers} without any more saving. |
| 401 | @item . |
| 402 | Save this buffer, then exit @code{save-some-buffers} without even asking |
| 403 | about other buffers. |
| 404 | @item C-r |
| 405 | View the buffer that you are currently being asked about. When you exit |
| 406 | View mode, you get back to @code{save-some-buffers}, which asks the |
| 407 | question again. |
| 408 | @item d |
| 409 | Diff the buffer against its corresponding file, so you can see what |
| 410 | changes you would be saving. This calls the command |
| 411 | @code{diff-buffer-with-file} (@pxref{Comparing Files}). |
| 412 | @item C-h |
| 413 | Display a help message about these options. |
| 414 | @end table |
| 415 | |
| 416 | @kbd{C-x C-c}, the key sequence to exit Emacs, invokes |
| 417 | @code{save-some-buffers} and therefore asks the same questions. |
| 418 | |
| 419 | @kindex M-~ |
| 420 | @findex not-modified |
| 421 | If you have changed a buffer but do not wish to save the changes, |
| 422 | you should take some action to prevent it. Otherwise, each time you |
| 423 | use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer |
| 424 | by mistake. One thing you can do is type @kbd{M-~} |
| 425 | (@code{not-modified}), which clears out the indication that the buffer |
| 426 | is modified. If you do this, none of the save commands will believe |
| 427 | that the buffer needs to be saved. (@samp{~} is often used as a |
| 428 | mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.) |
| 429 | Alternatively, you can cancel all the changes made since the file was |
| 430 | visited or saved, by reading the text from the file again. This is |
| 431 | called @dfn{reverting}. @xref{Reverting}. (You could also undo all |
| 432 | the changes by repeating the undo command @kbd{C-x u} until you have |
| 433 | undone all the changes; but reverting is easier.) |
| 434 | |
| 435 | @findex set-visited-file-name |
| 436 | @kbd{M-x set-visited-file-name} alters the name of the file that the |
| 437 | current buffer is visiting. It reads the new file name using the |
| 438 | minibuffer. Then it marks the buffer as visiting that file name, and |
| 439 | changes the buffer name correspondingly. @code{set-visited-file-name} |
| 440 | does not save the buffer in the newly visited file; it just alters the |
| 441 | records inside Emacs in case you do save later. It also marks the |
| 442 | buffer as ``modified'' so that @kbd{C-x C-s} in that buffer |
| 443 | @emph{will} save. |
| 444 | |
| 445 | @kindex C-x C-w |
| 446 | @findex write-file |
| 447 | If you wish to mark the buffer as visiting a different file and save |
| 448 | it right away, use @kbd{C-x C-w} (@code{write-file}). This is |
| 449 | equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}, |
| 450 | except that @kbd{C-x C-w} asks for confirmation if the file exists. |
| 451 | @kbd{C-x C-s} used on a buffer that is not visiting a file has the |
| 452 | same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the |
| 453 | buffer as visiting that file, and saves it there. The default file |
| 454 | name in a buffer that is not visiting a file is made by combining the |
| 455 | buffer name with the buffer's default directory (@pxref{File Names}). |
| 456 | |
| 457 | If the new file name implies a major mode, then @kbd{C-x C-w} switches |
| 458 | to that major mode, in most cases. The command |
| 459 | @code{set-visited-file-name} also does this. @xref{Choosing Modes}. |
| 460 | |
| 461 | If Emacs is about to save a file and sees that the date of the latest |
| 462 | version on disk does not match what Emacs last read or wrote, Emacs |
| 463 | notifies you of this fact, because it probably indicates a problem caused |
| 464 | by simultaneous editing and requires your immediate attention. |
| 465 | @xref{Interlocking,, Simultaneous Editing}. |
| 466 | |
| 467 | @node Backup |
| 468 | @subsection Backup Files |
| 469 | @cindex backup file |
| 470 | @vindex make-backup-files |
| 471 | @vindex vc-make-backup-files |
| 472 | |
| 473 | On most operating systems, rewriting a file automatically destroys all |
| 474 | record of what the file used to contain. Thus, saving a file from Emacs |
| 475 | throws away the old contents of the file---or it would, except that |
| 476 | Emacs carefully copies the old contents to another file, called the |
| 477 | @dfn{backup} file, before actually saving. |
| 478 | |
| 479 | Emacs makes a backup for a file only the first time the file is |
| 480 | saved from a buffer. No matter how many times you subsequently save |
| 481 | the file, its backup remains unchanged. However, if you kill the |
| 482 | buffer and then visit the file again, a new backup file will be made. |
| 483 | |
| 484 | For most files, the variable @code{make-backup-files} determines |
| 485 | whether to make backup files. On most operating systems, its default |
| 486 | value is @code{t}, so that Emacs does write backup files. |
| 487 | |
| 488 | For files managed by a version control system (@pxref{Version |
| 489 | Control}), the variable @code{vc-make-backup-files} determines whether |
| 490 | to make backup files. By default it is @code{nil}, since backup files |
| 491 | are redundant when you store all the previous versions in a version |
| 492 | control system. |
| 493 | @iftex |
| 494 | @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. |
| 495 | @end iftex |
| 496 | @ifnottex |
| 497 | @xref{General VC Options}. |
| 498 | @end ifnottex |
| 499 | |
| 500 | At your option, Emacs can keep either a single backup for each file, |
| 501 | or make a series of numbered backup files for each file that you edit. |
| 502 | @xref{Backup Names}. |
| 503 | |
| 504 | @vindex backup-enable-predicate |
| 505 | @vindex temporary-file-directory |
| 506 | @vindex small-temporary-file-directory |
| 507 | The default value of the @code{backup-enable-predicate} variable |
| 508 | prevents backup files being written for files in the directories used |
| 509 | for temporary files, specified by @code{temporary-file-directory} or |
| 510 | @code{small-temporary-file-directory}. |
| 511 | |
| 512 | You can explicitly tell Emacs to make another backup file from a |
| 513 | buffer, even though that buffer has been saved before. If you save |
| 514 | the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made |
| 515 | into a backup file if you save the buffer again. @kbd{C-u C-u C-x |
| 516 | C-s} saves the buffer, but first makes the previous file contents into |
| 517 | a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it |
| 518 | makes a backup from the previous contents, and arranges to make |
| 519 | another from the newly saved contents if you save again. |
| 520 | |
| 521 | @menu |
| 522 | * Names: Backup Names. How backup files are named. |
| 523 | * Deletion: Backup Deletion. Emacs deletes excess numbered backups. |
| 524 | * Copying: Backup Copying. Backups can be made by copying or renaming. |
| 525 | @end menu |
| 526 | |
| 527 | @node Backup Names |
| 528 | @subsubsection Single or Numbered Backups |
| 529 | |
| 530 | When Emacs makes a backup file, its name is normally constructed by |
| 531 | appending @samp{~} to the file name being edited; thus, the backup |
| 532 | file for @file{eval.c} would be @file{eval.c~}. |
| 533 | |
| 534 | If access control stops Emacs from writing backup files under the |
| 535 | usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}. |
| 536 | Only one such file can exist, so only the most recently made such |
| 537 | backup is available. |
| 538 | |
| 539 | Emacs can also make @dfn{numbered backup files}. Numbered backup |
| 540 | file names contain @samp{.~}, the number, and another @samp{~} after |
| 541 | the original file name. Thus, the backup files of @file{eval.c} would |
| 542 | be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way |
| 543 | through names like @file{eval.c.~259~} and beyond. |
| 544 | |
| 545 | @vindex version-control |
| 546 | The variable @code{version-control} determines whether to make |
| 547 | single backup files or multiple numbered backup files. Its possible |
| 548 | values are: |
| 549 | |
| 550 | @table @code |
| 551 | @item nil |
| 552 | Make numbered backups for files that have numbered backups already. |
| 553 | Otherwise, make single backups. This is the default. |
| 554 | @item t |
| 555 | Make numbered backups. |
| 556 | @item never |
| 557 | Never make numbered backups; always make single backups. |
| 558 | @end table |
| 559 | |
| 560 | @noindent |
| 561 | The usual way to set this variable is globally, through your init file |
| 562 | or the customization buffer. However, you can set |
| 563 | @code{version-control} locally in an individual buffer to control the |
| 564 | making of backups for that buffer's file (@pxref{Locals}). You can |
| 565 | have Emacs set @code{version-control} locally whenever you visit a |
| 566 | given file (@pxref{File Variables}). Some modes, such as Rmail mode, |
| 567 | set this variable. |
| 568 | |
| 569 | @cindex @env{VERSION_CONTROL} environment variable |
| 570 | If you set the environment variable @env{VERSION_CONTROL}, to tell |
| 571 | various GNU utilities what to do with backup files, Emacs also obeys the |
| 572 | environment variable by setting the Lisp variable @code{version-control} |
| 573 | accordingly at startup. If the environment variable's value is @samp{t} |
| 574 | or @samp{numbered}, then @code{version-control} becomes @code{t}; if the |
| 575 | value is @samp{nil} or @samp{existing}, then @code{version-control} |
| 576 | becomes @code{nil}; if it is @samp{never} or @samp{simple}, then |
| 577 | @code{version-control} becomes @code{never}. |
| 578 | |
| 579 | @vindex backup-directory-alist |
| 580 | You can customize the variable @code{backup-directory-alist} to |
| 581 | specify that files matching certain patterns should be backed up in |
| 582 | specific directories. This variable applies to both single and |
| 583 | numbered backups. A typical use is to add an element @code{("." |
| 584 | . @var{dir})} to make all backups in the directory with absolute name |
| 585 | @var{dir}; Emacs modifies the backup file names to avoid clashes |
| 586 | between files with the same names originating in different |
| 587 | directories. Alternatively, adding, @code{("." . ".~")} would make |
| 588 | backups in the invisible subdirectory @file{.~} of the original file's |
| 589 | directory. Emacs creates the directory, if necessary, to make the |
| 590 | backup. |
| 591 | |
| 592 | @vindex make-backup-file-name-function |
| 593 | If you define the variable @code{make-backup-file-name-function} to |
| 594 | a suitable Lisp function, that overrides the usual way Emacs |
| 595 | constructs backup file names. |
| 596 | |
| 597 | @node Backup Deletion |
| 598 | @subsubsection Automatic Deletion of Backups |
| 599 | |
| 600 | To prevent excessive consumption of disk space, Emacs can delete numbered |
| 601 | backup versions automatically. Generally Emacs keeps the first few backups |
| 602 | and the latest few backups, deleting any in between. This happens every |
| 603 | time a new backup is made. |
| 604 | |
| 605 | @vindex kept-old-versions |
| 606 | @vindex kept-new-versions |
| 607 | The two variables @code{kept-old-versions} and |
| 608 | @code{kept-new-versions} control this deletion. Their values are, |
| 609 | respectively, the number of oldest (lowest-numbered) backups to keep |
| 610 | and the number of newest (highest-numbered) ones to keep, each time a |
| 611 | new backup is made. The backups in the middle (excluding those oldest |
| 612 | and newest) are the excess middle versions---those backups are |
| 613 | deleted. These variables' values are used when it is time to delete |
| 614 | excess versions, just after a new backup version is made; the newly |
| 615 | made backup is included in the count in @code{kept-new-versions}. By |
| 616 | default, both variables are 2. |
| 617 | |
| 618 | @vindex delete-old-versions |
| 619 | If @code{delete-old-versions} is @code{t}, Emacs deletes the excess |
| 620 | backup files silently. If it is @code{nil}, the default, Emacs asks |
| 621 | you whether it should delete the excess backup versions. If it has |
| 622 | any other value, then Emacs never automatically deletes backups. |
| 623 | |
| 624 | Dired's @kbd{.} (Period) command can also be used to delete old versions. |
| 625 | @xref{Dired Deletion}. |
| 626 | |
| 627 | @node Backup Copying |
| 628 | @subsubsection Copying vs.@: Renaming |
| 629 | |
| 630 | Backup files can be made by copying the old file or by renaming it. |
| 631 | This makes a difference when the old file has multiple names (hard |
| 632 | links). If the old file is renamed into the backup file, then the |
| 633 | alternate names become names for the backup file. If the old file is |
| 634 | copied instead, then the alternate names remain names for the file |
| 635 | that you are editing, and the contents accessed by those names will be |
| 636 | the new contents. |
| 637 | |
| 638 | The method of making a backup file may also affect the file's owner |
| 639 | and group. If copying is used, these do not change. If renaming is used, |
| 640 | you become the file's owner, and the file's group becomes the default |
| 641 | (different operating systems have different defaults for the group). |
| 642 | |
| 643 | @vindex backup-by-copying |
| 644 | @vindex backup-by-copying-when-linked |
| 645 | @vindex backup-by-copying-when-mismatch |
| 646 | @vindex backup-by-copying-when-privileged-mismatch |
| 647 | @cindex file ownership, and backup |
| 648 | @cindex backup, and user-id |
| 649 | The choice of renaming or copying is made as follows: |
| 650 | |
| 651 | @itemize |
| 652 | @item |
| 653 | If the variable @code{backup-by-copying} is non-@code{nil} (the |
| 654 | default is @code{nil}), use copying. |
| 655 | |
| 656 | @item |
| 657 | Otherwise, if the variable @code{backup-by-copying-when-linked} is |
| 658 | non-@code{nil} (the default is @code{nil}), and the file has multiple |
| 659 | names, use copying. |
| 660 | |
| 661 | @item |
| 662 | Otherwise, if the variable @code{backup-by-copying-when-mismatch} is |
| 663 | non-@code{nil} (the default is @code{t}), and renaming would change |
| 664 | the file's owner or group, use copying. |
| 665 | |
| 666 | If you change @code{backup-by-copying-when-mismatch} to @code{nil}, |
| 667 | Emacs checks the numeric user-id of the file's owner. If this is |
| 668 | higher than @code{backup-by-copying-when-privileged-mismatch}, then it |
| 669 | behaves as though @code{backup-by-copying-when-mismatch} is |
| 670 | non-@code{nil} anyway. |
| 671 | |
| 672 | @item |
| 673 | Otherwise, renaming is the default choice. |
| 674 | @end itemize |
| 675 | |
| 676 | When a file is managed with a version control system (@pxref{Version |
| 677 | Control}), Emacs does not normally make backups in the usual way for |
| 678 | that file. But check-in and check-out are similar in some ways to |
| 679 | making backups. One unfortunate similarity is that these operations |
| 680 | typically break hard links, disconnecting the file name you visited from |
| 681 | any alternate names for the same file. This has nothing to do with |
| 682 | Emacs---the version control system does it. |
| 683 | |
| 684 | @node Customize Save |
| 685 | @subsection Customizing Saving of Files |
| 686 | |
| 687 | @vindex require-final-newline |
| 688 | If the value of the variable @code{require-final-newline} is |
| 689 | @code{t}, saving or writing a file silently puts a newline at the end |
| 690 | if there isn't already one there. If the value is @code{visit}, Emacs |
| 691 | adds a newline at the end of any file that doesn't have one, just |
| 692 | after it visits the file. (This marks the buffer as modified, and you |
| 693 | can undo it.) If the value is @code{visit-save}, Emacs adds such |
| 694 | newlines both on visiting and on saving. If the value is @code{nil}, |
| 695 | Emacs leaves the end of the file unchanged; any other non-@code{nil} |
| 696 | value means to asks you whether to add a newline. The default is |
| 697 | @code{nil}. |
| 698 | |
| 699 | @vindex mode-require-final-newline |
| 700 | Some major modes are designed for specific kinds of files that are |
| 701 | always supposed to end in newlines. Such major modes set the variable |
| 702 | @code{require-final-newline} to the value of |
| 703 | @code{mode-require-final-newline}, which defaults to @code{t}. By |
| 704 | setting the latter variable, you can control how these modes handle |
| 705 | final newlines. |
| 706 | |
| 707 | @vindex write-region-inhibit-fsync |
| 708 | When Emacs saves a file, it invokes the @code{fsync} system call to |
| 709 | force the data immediately out to disk. This is important for safety |
| 710 | if the system crashes or in case of power outage. However, it can be |
| 711 | disruptive on laptops using power saving, as it may force a disk |
| 712 | spin-up each time you save a file. If you accept an increased risk of |
| 713 | data loss, you can set @code{write-region-inhibit-fsync} to a |
| 714 | non-@code{nil} value to disable the synchronization. |
| 715 | |
| 716 | @node Interlocking |
| 717 | @subsection Protection against Simultaneous Editing |
| 718 | |
| 719 | @cindex file dates |
| 720 | @cindex simultaneous editing |
| 721 | Simultaneous editing occurs when two users visit the same file, both |
| 722 | make changes, and then both save them. If nobody is informed that |
| 723 | this is happening, whichever user saves first would later find that |
| 724 | his changes were lost. |
| 725 | |
| 726 | On some systems, Emacs notices immediately when the second user starts |
| 727 | to change the file, and issues an immediate warning. On all systems, |
| 728 | Emacs checks when you save the file, and warns if you are about to |
| 729 | overwrite another user's changes. You can prevent loss of the other |
| 730 | user's work by taking the proper corrective action instead of saving the |
| 731 | file. |
| 732 | |
| 733 | @findex ask-user-about-lock |
| 734 | @cindex locking files |
| 735 | When you make the first modification in an Emacs buffer that is |
| 736 | visiting a file, Emacs records that the file is @dfn{locked} by you. |
| 737 | (It does this by creating a specially-named symbolic link in the same |
| 738 | directory.) Emacs removes the lock when you save the changes. The |
| 739 | idea is that the file is locked whenever an Emacs buffer visiting it |
| 740 | has unsaved changes. |
| 741 | |
| 742 | @vindex create-lockfiles |
| 743 | You can prevent the creation of lock files by setting the variable |
| 744 | @code{create-lockfiles} to @code{nil}. @strong{Caution:} by |
| 745 | doing so you will lose the benefits that this feature provides. |
| 746 | |
| 747 | @cindex collision |
| 748 | If you begin to modify the buffer while the visited file is locked by |
| 749 | someone else, this constitutes a @dfn{collision}. When Emacs detects a |
| 750 | collision, it asks you what to do, by calling the Lisp function |
| 751 | @code{ask-user-about-lock}. You can redefine this function for the sake |
| 752 | of customization. The standard definition of this function asks you a |
| 753 | question and accepts three possible answers: |
| 754 | |
| 755 | @table @kbd |
| 756 | @item s |
| 757 | Steal the lock. Whoever was already changing the file loses the lock, |
| 758 | and you gain the lock. |
| 759 | @item p |
| 760 | Proceed. Go ahead and edit the file despite its being locked by someone else. |
| 761 | @item q |
| 762 | Quit. This causes an error (@code{file-locked}), and the buffer |
| 763 | contents remain unchanged---the modification you were trying to make |
| 764 | does not actually take place. |
| 765 | @end table |
| 766 | |
| 767 | If Emacs or the operating system crashes, this may leave behind lock |
| 768 | files which are stale, so you may occasionally get warnings about |
| 769 | spurious collisions. When you determine that the collision is |
| 770 | spurious, just use @kbd{p} to tell Emacs to go ahead anyway. |
| 771 | |
| 772 | Note that locking works on the basis of a file name; if a file has |
| 773 | multiple names, Emacs does not prevent two users from editing it |
| 774 | simultaneously under different names. |
| 775 | |
| 776 | A lock file cannot be written in some circumstances, e.g. if Emacs |
| 777 | lacks the system permissions or the system does not support symbolic |
| 778 | links. In these cases, Emacs can still detect the collision when you |
| 779 | try to save a file, by checking the file's last-modification date. If |
| 780 | the file has changed since the last time Emacs visited or saved it, |
| 781 | that implies that changes have been made in some other way, and will |
| 782 | be lost if Emacs proceeds with saving. Emacs then displays a warning |
| 783 | message and asks for confirmation before saving; answer @kbd{yes} to |
| 784 | save, and @kbd{no} or @kbd{C-g} cancel the save. |
| 785 | |
| 786 | If you are notified that simultaneous editing has already taken |
| 787 | place, one way to compare the buffer to its file is the @kbd{M-x |
| 788 | diff-buffer-with-file} command. @xref{Comparing Files}. |
| 789 | |
| 790 | @node File Shadowing |
| 791 | @subsection Shadowing Files |
| 792 | @cindex shadow files |
| 793 | @cindex file shadows |
| 794 | @findex shadow-initialize |
| 795 | |
| 796 | @table @kbd |
| 797 | @item M-x shadow-initialize |
| 798 | Set up file shadowing. |
| 799 | @item M-x shadow-define-literal-group |
| 800 | Declare a single file to be shared between sites. |
| 801 | @item M-x shadow-define-regexp-group |
| 802 | Make all files that match each of a group of files be shared between hosts. |
| 803 | @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} |
| 804 | Define a shadow file cluster @var{name}. |
| 805 | @item M-x shadow-copy-files |
| 806 | Copy all pending shadow files. |
| 807 | @item M-x shadow-cancel |
| 808 | Cancel the instruction to shadow some files. |
| 809 | @end table |
| 810 | |
| 811 | You can arrange to keep identical @dfn{shadow} copies of certain files |
| 812 | in more than one place---possibly on different machines. To do this, |
| 813 | first you must set up a @dfn{shadow file group}, which is a set of |
| 814 | identically-named files shared between a list of sites. The file |
| 815 | group is permanent and applies to further Emacs sessions as well as |
| 816 | the current one. Once the group is set up, every time you exit Emacs, |
| 817 | it will copy the file you edited to the other files in its group. You |
| 818 | can also do the copying without exiting Emacs, by typing @kbd{M-x |
| 819 | shadow-copy-files}. |
| 820 | |
| 821 | To set up a shadow file group, use @kbd{M-x |
| 822 | shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. |
| 823 | See their documentation strings for further information. |
| 824 | |
| 825 | Before copying a file to its shadows, Emacs asks for confirmation. |
| 826 | You can answer ``no'' to bypass copying of this file, this time. If |
| 827 | you want to cancel the shadowing permanently for a certain file, use |
| 828 | @kbd{M-x shadow-cancel} to eliminate or change the shadow file group. |
| 829 | |
| 830 | A @dfn{shadow cluster} is a group of hosts that share directories, so |
| 831 | that copying to or from one of them is sufficient to update the file |
| 832 | on all of them. Each shadow cluster has a name, and specifies the |
| 833 | network address of a primary host (the one we copy files to), and a |
| 834 | regular expression that matches the host names of all the other hosts |
| 835 | in the cluster. You can define a shadow cluster with @kbd{M-x |
| 836 | shadow-define-cluster}. |
| 837 | |
| 838 | @node Time Stamps |
| 839 | @subsection Updating Time Stamps Automatically |
| 840 | @cindex time stamps |
| 841 | @cindex modification dates |
| 842 | @cindex locale, date format |
| 843 | |
| 844 | You can arrange to put a time stamp in a file, so that it is updated |
| 845 | automatically each time you edit and save the file. The time stamp |
| 846 | must be in the first eight lines of the file, and you should insert it |
| 847 | like this: |
| 848 | |
| 849 | @example |
| 850 | Time-stamp: <> |
| 851 | @end example |
| 852 | |
| 853 | @noindent |
| 854 | or like this: |
| 855 | |
| 856 | @example |
| 857 | Time-stamp: " " |
| 858 | @end example |
| 859 | |
| 860 | @findex time-stamp |
| 861 | Then add the function @code{time-stamp} to the hook |
| 862 | @code{before-save-hook} (@pxref{Hooks}). When you save the file, this |
| 863 | function then automatically updates the time stamp with the current |
| 864 | date and time. You can also use the command @kbd{M-x time-stamp} to |
| 865 | update the time stamp manually. For other customizations, see the |
| 866 | Custom group @code{time-stamp}. Note that the time stamp is formatted |
| 867 | according to your locale setting (@pxref{Environment}). |
| 868 | |
| 869 | @node Reverting |
| 870 | @section Reverting a Buffer |
| 871 | @findex revert-buffer |
| 872 | @cindex drastic changes |
| 873 | @cindex reread a file |
| 874 | |
| 875 | If you have made extensive changes to a file-visiting buffer and |
| 876 | then change your mind, you can @dfn{revert} the changes and go back to |
| 877 | the saved version of the file. To do this, type @kbd{M-x |
| 878 | revert-buffer}. Since reverting unintentionally could lose a lot of |
| 879 | work, Emacs asks for confirmation first. |
| 880 | |
| 881 | The @code{revert-buffer} command tries to position point in such a |
| 882 | way that, if the file was edited only slightly, you will be at |
| 883 | approximately the same part of the text as before. But if you have |
| 884 | made major changes, point may end up in a totally different location. |
| 885 | |
| 886 | Reverting marks the buffer as ``not modified''. It also clears the |
| 887 | buffer's undo history (@pxref{Undo}). Thus, the reversion cannot be |
| 888 | undone---if you change your mind yet again, you can't use the undo |
| 889 | commands to bring the reverted changes back. |
| 890 | |
| 891 | Some kinds of buffers that are not associated with files, such as |
| 892 | Dired buffers, can also be reverted. For them, reverting means |
| 893 | recalculating their contents. Buffers created explicitly with |
| 894 | @kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error |
| 895 | if you try. |
| 896 | |
| 897 | @vindex revert-without-query |
| 898 | When you edit a file that changes automatically and frequently---for |
| 899 | example, a log of output from a process that continues to run---it may |
| 900 | be useful for Emacs to revert the file without querying you. To |
| 901 | request this behavior, set the variable @code{revert-without-query} to |
| 902 | a list of regular expressions. When a file name matches one of these |
| 903 | regular expressions, @code{find-file} and @code{revert-buffer} will |
| 904 | revert it automatically if it has changed---provided the buffer itself |
| 905 | is not modified. (If you have edited the text, it would be wrong to |
| 906 | discard your changes.) |
| 907 | |
| 908 | @cindex Global Auto-Revert mode |
| 909 | @cindex mode, Global Auto-Revert |
| 910 | @cindex Auto-Revert mode |
| 911 | @cindex mode, Auto-Revert |
| 912 | @findex global-auto-revert-mode |
| 913 | @findex auto-revert-mode |
| 914 | @findex auto-revert-tail-mode |
| 915 | @vindex auto-revert-interval |
| 916 | You can also tell Emacs to revert buffers periodically. To do this |
| 917 | for a specific buffer, enable the minor mode Auto-Revert mode by |
| 918 | typing @kbd{M-x auto-revert-mode}. This automatically reverts the |
| 919 | current buffer every five seconds; you can change the interval through |
| 920 | the variable @code{auto-revert-interval}. To do the same for all file |
| 921 | buffers, type @kbd{M-x global-auto-revert-mode} to enable Global |
| 922 | Auto-Revert mode. These minor modes do not check or revert remote |
| 923 | files, because that is usually too slow. |
| 924 | |
| 925 | One use of Auto-Revert mode is to ``tail'' a file such as a system |
| 926 | log, so that changes made to that file by other programs are |
| 927 | continuously displayed. To do this, just move the point to the end of |
| 928 | the buffer, and it will stay there as the file contents change. |
| 929 | However, if you are sure that the file will only change by growing at |
| 930 | the end, use Auto-Revert Tail mode instead |
| 931 | (@code{auto-revert-tail-mode}). It is more efficient for this. |
| 932 | Auto-Revert Tail mode works also for remote files. |
| 933 | |
| 934 | @xref{VC Undo}, for commands to revert to earlier versions of files |
| 935 | under version control. @xref{VC Mode Line}, for Auto Revert |
| 936 | peculiarities when visiting files under version control. |
| 937 | |
| 938 | @ifnottex |
| 939 | @include arevert-xtra.texi |
| 940 | @end ifnottex |
| 941 | |
| 942 | @node Auto Save |
| 943 | @section Auto-Saving: Protection Against Disasters |
| 944 | @cindex Auto Save mode |
| 945 | @cindex mode, Auto Save |
| 946 | @cindex crashes |
| 947 | |
| 948 | From time to time, Emacs automatically saves each visited file in a |
| 949 | separate file, without altering the file you actually use. This is |
| 950 | called @dfn{auto-saving}. It prevents you from losing more than a |
| 951 | limited amount of work if the system crashes. |
| 952 | |
| 953 | When Emacs determines that it is time for auto-saving, it considers |
| 954 | each buffer, and each is auto-saved if auto-saving is enabled for it |
| 955 | and it has been changed since the last time it was auto-saved. The |
| 956 | message @samp{Auto-saving...} is displayed in the echo area during |
| 957 | auto-saving, if any files are actually auto-saved. Errors occurring |
| 958 | during auto-saving are caught so that they do not interfere with the |
| 959 | execution of commands you have been typing. |
| 960 | |
| 961 | @menu |
| 962 | * Files: Auto Save Files. The file where auto-saved changes are |
| 963 | actually made until you save the file. |
| 964 | * Control: Auto Save Control. Controlling when and how often to auto-save. |
| 965 | * Recover:: Recovering text from auto-save files. |
| 966 | @end menu |
| 967 | |
| 968 | @node Auto Save Files |
| 969 | @subsection Auto-Save Files |
| 970 | |
| 971 | Auto-saving does not normally save in the files that you visited, |
| 972 | because it can be very undesirable to save a change that you did not |
| 973 | want to make permanent. Instead, auto-saving is done in a different |
| 974 | file called the @dfn{auto-save file}, and the visited file is changed |
| 975 | only when you request saving explicitly (such as with @kbd{C-x C-s}). |
| 976 | |
| 977 | Normally, the auto-save file name is made by appending @samp{#} to the |
| 978 | front and rear of the visited file name. Thus, a buffer visiting file |
| 979 | @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that |
| 980 | are not visiting files are auto-saved only if you request it explicitly; |
| 981 | when they are auto-saved, the auto-save file name is made by appending |
| 982 | @samp{#} to the front and rear of buffer name, then |
| 983 | adding digits and letters at the end for uniqueness. For |
| 984 | example, the @file{*mail*} buffer in which you compose messages to be |
| 985 | sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file |
| 986 | names are made this way unless you reprogram parts of Emacs to do |
| 987 | something different (the functions @code{make-auto-save-file-name} and |
| 988 | @code{auto-save-file-name-p}). The file name to be used for auto-saving |
| 989 | in a buffer is calculated when auto-saving is turned on in that buffer. |
| 990 | |
| 991 | @cindex auto-save for remote files |
| 992 | @vindex auto-save-file-name-transforms |
| 993 | The variable @code{auto-save-file-name-transforms} allows a degree |
| 994 | of control over the auto-save file name. It lets you specify a series |
| 995 | of regular expressions and replacements to transform the auto save |
| 996 | file name. The default value puts the auto-save files for remote |
| 997 | files (@pxref{Remote Files}) into the temporary file directory on the |
| 998 | local machine. |
| 999 | |
| 1000 | When you delete a substantial part of the text in a large buffer, auto |
| 1001 | save turns off temporarily in that buffer. This is because if you |
| 1002 | deleted the text unintentionally, you might find the auto-save file more |
| 1003 | useful if it contains the deleted text. To reenable auto-saving after |
| 1004 | this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x |
| 1005 | auto-save-mode}. |
| 1006 | |
| 1007 | @vindex auto-save-visited-file-name |
| 1008 | If you want auto-saving to be done in the visited file rather than |
| 1009 | in a separate auto-save file, set the variable |
| 1010 | @code{auto-save-visited-file-name} to a non-@code{nil} value. In this |
| 1011 | mode, there is no real difference between auto-saving and explicit |
| 1012 | saving. |
| 1013 | |
| 1014 | @vindex delete-auto-save-files |
| 1015 | A buffer's auto-save file is deleted when you save the buffer in its |
| 1016 | visited file. (You can inhibit this by setting the variable |
| 1017 | @code{delete-auto-save-files} to @code{nil}.) Changing the visited |
| 1018 | file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames |
| 1019 | any auto-save file to go with the new visited name. |
| 1020 | |
| 1021 | @node Auto Save Control |
| 1022 | @subsection Controlling Auto-Saving |
| 1023 | |
| 1024 | @vindex auto-save-default |
| 1025 | @findex auto-save-mode |
| 1026 | Each time you visit a file, auto-saving is turned on for that file's |
| 1027 | buffer if the variable @code{auto-save-default} is non-@code{nil} (but |
| 1028 | not in batch mode; @pxref{Initial Options}). The default for this |
| 1029 | variable is @code{t}, so auto-saving is the usual practice for |
| 1030 | file-visiting buffers. To toggle auto-saving in the current buffer, |
| 1031 | type @kbd{M-x auto-save-mode}. Auto Save mode acts as a buffer-local |
| 1032 | minor mode (@pxref{Minor Modes}). |
| 1033 | |
| 1034 | @vindex auto-save-interval |
| 1035 | Emacs auto-saves periodically based on how many characters you have |
| 1036 | typed since the last auto-save. The variable |
| 1037 | @code{auto-save-interval} specifies how many characters there are |
| 1038 | between auto-saves. By default, it is 300. Emacs doesn't accept |
| 1039 | values that are too small: if you customize @code{auto-save-interval} |
| 1040 | to a value less than 20, Emacs will behave as if the value is 20. |
| 1041 | |
| 1042 | @vindex auto-save-timeout |
| 1043 | Auto-saving also takes place when you stop typing for a while. By |
| 1044 | default, it does this after 30 seconds of idleness (at this time, |
| 1045 | Emacs may also perform garbage collection; @pxref{Garbage |
| 1046 | Collection,,, elisp, The Emacs Lisp Reference Manual}). To change |
| 1047 | this interval, customize the variable @code{auto-save-timeout}. The |
| 1048 | actual time period is longer if the current buffer is long; this is a |
| 1049 | heuristic which aims to keep out of your way when you are editing long |
| 1050 | buffers, in which auto-save takes an appreciable amount of time. |
| 1051 | Auto-saving during idle periods accomplishes two things: first, it |
| 1052 | makes sure all your work is saved if you go away from the terminal for |
| 1053 | a while; second, it may avoid some auto-saving while you are actually |
| 1054 | typing. |
| 1055 | |
| 1056 | Emacs also does auto-saving whenever it gets a fatal error. This |
| 1057 | includes killing the Emacs job with a shell command such as @samp{kill |
| 1058 | %emacs}, or disconnecting a phone line or network connection. |
| 1059 | |
| 1060 | @findex do-auto-save |
| 1061 | You can perform an auto-save explicitly with the command @kbd{M-x |
| 1062 | do-auto-save}. |
| 1063 | |
| 1064 | @node Recover |
| 1065 | @subsection Recovering Data from Auto-Saves |
| 1066 | |
| 1067 | @findex recover-file |
| 1068 | You can use the contents of an auto-save file to recover from a loss |
| 1069 | of data with the command @kbd{M-x recover-file @key{RET} @var{file} |
| 1070 | @key{RET}}. This visits @var{file} and then (after your confirmation) |
| 1071 | restores the contents from its auto-save file @file{#@var{file}#}. |
| 1072 | You can then save with @kbd{C-x C-s} to put the recovered text into |
| 1073 | @var{file} itself. For example, to recover file @file{foo.c} from its |
| 1074 | auto-save file @file{#foo.c#}, do:@refill |
| 1075 | |
| 1076 | @example |
| 1077 | M-x recover-file @key{RET} foo.c @key{RET} |
| 1078 | yes @key{RET} |
| 1079 | C-x C-s |
| 1080 | @end example |
| 1081 | |
| 1082 | Before asking for confirmation, @kbd{M-x recover-file} displays a |
| 1083 | directory listing describing the specified file and the auto-save file, |
| 1084 | so you can compare their sizes and dates. If the auto-save file |
| 1085 | is older, @kbd{M-x recover-file} does not offer to read it. |
| 1086 | |
| 1087 | @findex recover-session |
| 1088 | If Emacs or the computer crashes, you can recover all the files you |
| 1089 | were editing from their auto save files with the command @kbd{M-x |
| 1090 | recover-session}. This first shows you a list of recorded interrupted |
| 1091 | sessions. Move point to the one you choose, and type @kbd{C-c C-c}. |
| 1092 | |
| 1093 | Then @code{recover-session} asks about each of the files that were |
| 1094 | being edited during that session, asking whether to recover that file. |
| 1095 | If you answer @kbd{y}, it calls @code{recover-file}, which works in its |
| 1096 | normal fashion. It shows the dates of the original file and its |
| 1097 | auto-save file, and asks once again whether to recover that file. |
| 1098 | |
| 1099 | When @code{recover-session} is done, the files you've chosen to |
| 1100 | recover are present in Emacs buffers. You should then save them. Only |
| 1101 | this---saving them---updates the files themselves. |
| 1102 | |
| 1103 | @vindex auto-save-list-file-prefix |
| 1104 | Emacs records information about interrupted sessions in files named |
| 1105 | @file{.saves-@var{pid}-@var{hostname}} in the directory |
| 1106 | @file{~/.emacs.d/auto-save-list/}. This directory is determined by |
| 1107 | the variable @code{auto-save-list-file-prefix}. If you set |
| 1108 | @code{auto-save-list-file-prefix} to @code{nil}, sessions are not |
| 1109 | recorded for recovery. |
| 1110 | |
| 1111 | @node File Aliases |
| 1112 | @section File Name Aliases |
| 1113 | @cindex symbolic links (visiting) |
| 1114 | @cindex hard links (visiting) |
| 1115 | |
| 1116 | Symbolic links and hard links both make it possible for several file |
| 1117 | names to refer to the same file. Hard links are alternate names that |
| 1118 | refer directly to the file; all the names are equally valid, and no one |
| 1119 | of them is preferred. By contrast, a symbolic link is a kind of defined |
| 1120 | alias: when @file{foo} is a symbolic link to @file{bar}, you can use |
| 1121 | either name to refer to the file, but @file{bar} is the real name, while |
| 1122 | @file{foo} is just an alias. More complex cases occur when symbolic |
| 1123 | links point to directories. |
| 1124 | |
| 1125 | @vindex find-file-existing-other-name |
| 1126 | @vindex find-file-suppress-same-file-warnings |
| 1127 | Normally, if you visit a file which Emacs is already visiting under |
| 1128 | a different name, Emacs displays a message in the echo area and uses |
| 1129 | the existing buffer visiting that file. This can happen on systems |
| 1130 | that support hard or symbolic links, or if you use a long file name on |
| 1131 | a system that truncates long file names, or on a case-insensitive file |
| 1132 | system. You can suppress the message by setting the variable |
| 1133 | @code{find-file-suppress-same-file-warnings} to a non-@code{nil} |
| 1134 | value. You can disable this feature entirely by setting the variable |
| 1135 | @code{find-file-existing-other-name} to @code{nil}: then if you visit |
| 1136 | the same file under two different names, you get a separate buffer for |
| 1137 | each file name. |
| 1138 | |
| 1139 | @vindex find-file-visit-truename |
| 1140 | @cindex truenames of files |
| 1141 | @cindex file truenames |
| 1142 | If the variable @code{find-file-visit-truename} is non-@code{nil}, |
| 1143 | then the file name recorded for a buffer is the file's @dfn{truename} |
| 1144 | (made by replacing all symbolic links with their target names), rather |
| 1145 | than the name you specify. Setting @code{find-file-visit-truename} also |
| 1146 | implies the effect of @code{find-file-existing-other-name}. |
| 1147 | |
| 1148 | @cindex directory name abbreviation |
| 1149 | @vindex directory-abbrev-alist |
| 1150 | Sometimes, a directory is ordinarily accessed through a symbolic |
| 1151 | link, and you may want Emacs to preferentially show its ``linked'' |
| 1152 | name. To do this, customize @code{directory-abbrev-alist}. Each |
| 1153 | element in this list should have the form @code{(@var{from} |
| 1154 | . @var{to})}, which means to replace @var{from} with @var{to} whenever |
| 1155 | @var{from} appears in a directory name. The @var{from} string is a |
| 1156 | regular expression (@pxref{Regexps}). It is matched against directory |
| 1157 | names anchored at the first character, and should start with @samp{\`} |
| 1158 | (to support directory names with embedded newlines, which would defeat |
| 1159 | @samp{^}). The @var{to} string should be an ordinary absolute |
| 1160 | directory name pointing to the same directory. Do not use @samp{~} to |
| 1161 | stand for a home directory in the @var{to} string; Emacs performs |
| 1162 | these substitutions separately. Here's an example, from a system on |
| 1163 | which @file{/home/fsf} is normally accessed through a symbolic link |
| 1164 | named @file{/fsf}: |
| 1165 | |
| 1166 | @example |
| 1167 | (("\\`/home/fsf" . "/fsf")) |
| 1168 | @end example |
| 1169 | |
| 1170 | @node Directories |
| 1171 | @section File Directories |
| 1172 | |
| 1173 | @cindex file directory |
| 1174 | @cindex directory listing |
| 1175 | The file system groups files into @dfn{directories}. A @dfn{directory |
| 1176 | listing} is a list of all the files in a directory. Emacs provides |
| 1177 | commands to create and delete directories, and to make directory |
| 1178 | listings in brief format (file names only) and verbose format (sizes, |
| 1179 | dates, and authors included). Emacs also includes a directory browser |
| 1180 | feature called Dired; see @ref{Dired}. |
| 1181 | |
| 1182 | @table @kbd |
| 1183 | @item C-x C-d @var{dir-or-pattern} @key{RET} |
| 1184 | Display a brief directory listing (@code{list-directory}). |
| 1185 | @item C-u C-x C-d @var{dir-or-pattern} @key{RET} |
| 1186 | Display a verbose directory listing. |
| 1187 | @item M-x make-directory @key{RET} @var{dirname} @key{RET} |
| 1188 | Create a new directory named @var{dirname}. |
| 1189 | @item M-x delete-directory @key{RET} @var{dirname} @key{RET} |
| 1190 | Delete the directory named @var{dirname}. If it isn't empty, |
| 1191 | you will be asked whether you want to delete it recursively. |
| 1192 | @end table |
| 1193 | |
| 1194 | @findex list-directory |
| 1195 | @kindex C-x C-d |
| 1196 | The command to display a directory listing is @kbd{C-x C-d} |
| 1197 | (@code{list-directory}). It reads using the minibuffer a file name |
| 1198 | which is either a directory to be listed or a wildcard-containing |
| 1199 | pattern for the files to be listed. For example, |
| 1200 | |
| 1201 | @example |
| 1202 | C-x C-d /u2/emacs/etc @key{RET} |
| 1203 | @end example |
| 1204 | |
| 1205 | @noindent |
| 1206 | lists all the files in directory @file{/u2/emacs/etc}. Here is an |
| 1207 | example of specifying a file name pattern: |
| 1208 | |
| 1209 | @example |
| 1210 | C-x C-d /u2/emacs/src/*.c @key{RET} |
| 1211 | @end example |
| 1212 | |
| 1213 | Normally, @kbd{C-x C-d} displays a brief directory listing containing |
| 1214 | just file names. A numeric argument (regardless of value) tells it to |
| 1215 | make a verbose listing including sizes, dates, and owners (like |
| 1216 | @samp{ls -l}). |
| 1217 | |
| 1218 | @vindex list-directory-brief-switches |
| 1219 | @vindex list-directory-verbose-switches |
| 1220 | The text of a directory listing is mostly obtained by running |
| 1221 | @code{ls} in an inferior process. Two Emacs variables control the |
| 1222 | switches passed to @code{ls}: @code{list-directory-brief-switches} is |
| 1223 | a string giving the switches to use in brief listings (@code{"-CF"} by |
| 1224 | default), and @code{list-directory-verbose-switches} is a string |
| 1225 | giving the switches to use in a verbose listing (@code{"-l"} by |
| 1226 | default). |
| 1227 | |
| 1228 | @vindex directory-free-space-program |
| 1229 | @vindex directory-free-space-args |
| 1230 | In verbose directory listings, Emacs adds information about the |
| 1231 | amount of free space on the disk that contains the directory. To do |
| 1232 | this, it runs the program specified by |
| 1233 | @code{directory-free-space-program} with arguments |
| 1234 | @code{directory-free-space-args}. |
| 1235 | |
| 1236 | The command @kbd{M-x delete-directory} prompts for a directory name |
| 1237 | using the minibuffer, and deletes the directory if it is empty. If |
| 1238 | the directory is not empty, you will be asked whether you want to |
| 1239 | delete it recursively. On systems that have a ``Trash'' (or ``Recycle |
| 1240 | Bin'') feature, you can make this command move the specified directory |
| 1241 | to the Trash instead of deleting it outright, by changing the variable |
| 1242 | @code{delete-by-moving-to-trash} to @code{t}. @xref{Misc File Ops}, |
| 1243 | for more information about using the Trash. |
| 1244 | |
| 1245 | @node Comparing Files |
| 1246 | @section Comparing Files |
| 1247 | @cindex comparing files |
| 1248 | |
| 1249 | @findex diff |
| 1250 | @vindex diff-switches |
| 1251 | The command @kbd{M-x diff} prompts for two file names, using the |
| 1252 | minibuffer, and displays the differences between the two files in a |
| 1253 | buffer named @file{*diff*}. This works by running the @command{diff} |
| 1254 | program, using options taken from the variable @code{diff-switches}. |
| 1255 | The value of @code{diff-switches} should be a string; the default is |
| 1256 | @code{"-c"} to specify a context diff. @xref{Top,, Diff, diff, |
| 1257 | Comparing and Merging Files}, for more information about the |
| 1258 | @command{diff} program. |
| 1259 | |
| 1260 | The output of the @code{diff} command is shown using a major mode |
| 1261 | called Diff mode. @xref{Diff Mode}. |
| 1262 | |
| 1263 | @findex diff-backup |
| 1264 | The command @kbd{M-x diff-backup} compares a specified file with its |
| 1265 | most recent backup. If you specify the name of a backup file, |
| 1266 | @code{diff-backup} compares it with the source file that it is a |
| 1267 | backup of. In all other respects, this behaves like @kbd{M-x diff}. |
| 1268 | |
| 1269 | @findex diff-buffer-with-file |
| 1270 | The command @kbd{M-x diff-buffer-with-file} compares a specified |
| 1271 | buffer with its corresponding file. This shows you what changes you |
| 1272 | would make to the file if you save the buffer. |
| 1273 | |
| 1274 | @findex compare-windows |
| 1275 | The command @kbd{M-x compare-windows} compares the text in the |
| 1276 | current window with that in the next window. (For more information |
| 1277 | about windows in Emacs, @ref{Windows}.) Comparison starts at point in |
| 1278 | each window, after pushing each initial point value on the mark ring |
| 1279 | in its respective buffer. Then it moves point forward in each window, |
| 1280 | one character at a time, until it reaches characters that don't match. |
| 1281 | Then the command exits. |
| 1282 | |
| 1283 | If point in the two windows is followed by non-matching text when |
| 1284 | the command starts, @kbd{M-x compare-windows} tries heuristically to |
| 1285 | advance up to matching text in the two windows, and then exits. So if |
| 1286 | you use @kbd{M-x compare-windows} repeatedly, each time it either |
| 1287 | skips one matching range or finds the start of another. |
| 1288 | |
| 1289 | @vindex compare-ignore-case |
| 1290 | @vindex compare-ignore-whitespace |
| 1291 | With a numeric argument, @code{compare-windows} ignores changes in |
| 1292 | whitespace. If the variable @code{compare-ignore-case} is |
| 1293 | non-@code{nil}, the comparison ignores differences in case as well. |
| 1294 | If the variable @code{compare-ignore-whitespace} is non-@code{nil}, |
| 1295 | @code{compare-windows} normally ignores changes in whitespace, and a |
| 1296 | prefix argument turns that off. |
| 1297 | |
| 1298 | @cindex Smerge mode |
| 1299 | @findex smerge-mode |
| 1300 | @cindex failed merges |
| 1301 | @cindex merges, failed |
| 1302 | @cindex comparing 3 files (@code{diff3}) |
| 1303 | You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor |
| 1304 | mode for editing output from the @command{diff3} program. This is |
| 1305 | typically the result of a failed merge from a version control system |
| 1306 | ``update'' outside VC, due to conflicting changes to a file. Smerge |
| 1307 | mode provides commands to resolve conflicts by selecting specific |
| 1308 | changes. |
| 1309 | |
| 1310 | @iftex |
| 1311 | @xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, |
| 1312 | @end iftex |
| 1313 | @ifnottex |
| 1314 | @xref{Emerge}, |
| 1315 | @end ifnottex |
| 1316 | for the Emerge facility, which provides a powerful interface for |
| 1317 | merging files. |
| 1318 | |
| 1319 | @node Diff Mode |
| 1320 | @section Diff Mode |
| 1321 | @cindex Diff mode |
| 1322 | @findex diff-mode |
| 1323 | @cindex patches, editing |
| 1324 | |
| 1325 | Diff mode is a major mode used for the output of @kbd{M-x diff} and |
| 1326 | other similar commands. This kind of output is called a @dfn{patch}, |
| 1327 | because it can be passed to the @command{patch} command to |
| 1328 | automatically apply the specified changes. To select Diff mode |
| 1329 | manually, type @kbd{M-x diff-mode}. |
| 1330 | |
| 1331 | @cindex hunk, diff |
| 1332 | The changes specified in a patch are grouped into @dfn{hunks}, which |
| 1333 | are contiguous chunks of text that contain one or more changed lines. |
| 1334 | Hunks can also include unchanged lines to provide context for the |
| 1335 | changes. Each hunk is preceded by a @dfn{hunk header}, which |
| 1336 | specifies the old and new line numbers at which the hunk occurs. Diff |
| 1337 | mode highlights each hunk header, to distinguish it from the actual |
| 1338 | contents of the hunk. |
| 1339 | |
| 1340 | @vindex diff-update-on-the-fly |
| 1341 | You can edit a Diff mode buffer like any other buffer. (If it is |
| 1342 | read-only, you need to make it writable first. @xref{Misc Buffer}.) |
| 1343 | Whenever you change a hunk, Diff mode attempts to automatically |
| 1344 | correct the line numbers in the hunk headers, to ensure that the diff |
| 1345 | remains ``correct''. To disable automatic line number correction, |
| 1346 | change the variable @code{diff-update-on-the-fly} to @code{nil}. |
| 1347 | |
| 1348 | Diff mode treats each hunk as an ``error message'', similar to |
| 1349 | Compilation mode. Thus, you can use commands such as @kbd{C-x '} to |
| 1350 | visit the corresponding source locations. @xref{Compilation Mode}. |
| 1351 | |
| 1352 | In addition, Diff mode provides the following commands to navigate, |
| 1353 | manipulate and apply parts of patches: |
| 1354 | |
| 1355 | @table @kbd |
| 1356 | @item M-n |
| 1357 | @findex diff-hunk-next |
| 1358 | Move to the next hunk-start (@code{diff-hunk-next}). |
| 1359 | |
| 1360 | @findex diff-auto-refine-mode |
| 1361 | @cindex mode, Diff Auto-Refine |
| 1362 | @cindex Diff Auto-Refine mode |
| 1363 | This command has a side effect: it @dfn{refines} the hunk you move to, |
| 1364 | highlighting its changes with better granularity. To disable this |
| 1365 | feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor |
| 1366 | mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by |
| 1367 | default, add this to your init file (@pxref{Hooks}): |
| 1368 | |
| 1369 | @example |
| 1370 | (add-hook 'diff-mode-hook |
| 1371 | (lambda () (diff-auto-refine-mode -1))) |
| 1372 | @end example |
| 1373 | |
| 1374 | @item M-p |
| 1375 | @findex diff-hunk-prev |
| 1376 | Move to the previous hunk-start (@code{diff-hunk-prev}). Like |
| 1377 | @kbd{M-n}, this has the side-effect of refining the hunk you move to, |
| 1378 | unless you disable Diff Auto-Refine mode. |
| 1379 | |
| 1380 | @item M-@} |
| 1381 | @findex diff-file-next |
| 1382 | Move to the next file-start, in a multi-file patch |
| 1383 | (@code{diff-file-next}). |
| 1384 | |
| 1385 | @item M-@{ |
| 1386 | @findex diff-file-prev |
| 1387 | Move to the previous file-start, in a multi-file patch |
| 1388 | (@code{diff-file-prev}). |
| 1389 | |
| 1390 | @item M-k |
| 1391 | @findex diff-hunk-kill |
| 1392 | Kill the hunk at point (@code{diff-hunk-kill}). |
| 1393 | |
| 1394 | @item M-K |
| 1395 | @findex diff-file-kill |
| 1396 | In a multi-file patch, kill the current file part. |
| 1397 | (@code{diff-file-kill}). |
| 1398 | |
| 1399 | @item C-c C-a |
| 1400 | @findex diff-apply-hunk |
| 1401 | Apply this hunk to its target file (@code{diff-apply-hunk}). With a |
| 1402 | prefix argument of @kbd{C-u}, revert this hunk. |
| 1403 | |
| 1404 | @item C-c C-b |
| 1405 | @findex diff-refine-hunk |
| 1406 | Highlight the changes of the hunk at point with a finer granularity |
| 1407 | (@code{diff-refine-hunk}). This allows you to see exactly which parts |
| 1408 | of each changed line were actually changed. |
| 1409 | |
| 1410 | @item C-c C-c |
| 1411 | @findex diff-goto-source |
| 1412 | Go to the source file and line corresponding to this hunk |
| 1413 | (@code{diff-goto-source}). |
| 1414 | |
| 1415 | @item C-c C-e |
| 1416 | @findex diff-ediff-patch |
| 1417 | Start an Ediff session with the patch (@code{diff-ediff-patch}). |
| 1418 | @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. |
| 1419 | |
| 1420 | @item C-c C-n |
| 1421 | @findex diff-restrict-view |
| 1422 | Restrict the view to the current hunk (@code{diff-restrict-view}). |
| 1423 | @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the |
| 1424 | view to the current file of a multiple-file patch. To widen again, |
| 1425 | use @kbd{C-x n w} (@code{widen}). |
| 1426 | |
| 1427 | @item C-c C-r |
| 1428 | @findex diff-reverse-direction |
| 1429 | Reverse the direction of comparison for the entire buffer |
| 1430 | (@code{diff-reverse-direction}). |
| 1431 | |
| 1432 | @item C-c C-s |
| 1433 | @findex diff-split-hunk |
| 1434 | Split the hunk at point (@code{diff-split-hunk}). This is for |
| 1435 | manually editing patches, and only works with the @dfn{unified diff |
| 1436 | format} produced by the @option{-u} or @option{--unified} options to |
| 1437 | the @command{diff} program. If you need to split a hunk in the |
| 1438 | @dfn{context diff format} produced by the @option{-c} or |
| 1439 | @option{--context} options to @command{diff}, first convert the buffer |
| 1440 | to the unified diff format with @kbd{C-c C-u}. |
| 1441 | |
| 1442 | @item C-c C-d |
| 1443 | @findex diff-unified->context |
| 1444 | Convert the entire buffer to the @dfn{context diff format} |
| 1445 | (@code{diff-unified->context}). With a prefix argument, convert only |
| 1446 | the text within the region. |
| 1447 | |
| 1448 | @item C-c C-u |
| 1449 | @findex diff-context->unified |
| 1450 | Convert the entire buffer to unified diff format |
| 1451 | (@code{diff-context->unified}). With a prefix argument, convert |
| 1452 | unified format to context format. When the mark is active, convert |
| 1453 | only the text within the region. |
| 1454 | |
| 1455 | @item C-c C-w |
| 1456 | @findex diff-refine-hunk |
| 1457 | Refine the current hunk so that it disregards changes in whitespace |
| 1458 | (@code{diff-refine-hunk}). |
| 1459 | |
| 1460 | @item C-x 4 A |
| 1461 | @findex diff-add-change-log-entries-other-window |
| 1462 | @findex add-change-log-entry-other-window@r{, in Diff mode} |
| 1463 | Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change |
| 1464 | Log}), for each one of the hunks |
| 1465 | (@code{diff-add-change-log-entries-other-window}). This creates a |
| 1466 | skeleton of the log of changes that you can later fill with the actual |
| 1467 | descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode |
| 1468 | operates on behalf of the current hunk's file, but gets the function |
| 1469 | name from the patch itself. This is useful for making log entries for |
| 1470 | functions that are deleted by the patch. |
| 1471 | @end table |
| 1472 | |
| 1473 | By default, Diff mode highlights trailing whitespace on modified |
| 1474 | lines, so that they are more obvious. This is done by enabling |
| 1475 | Whitespace mode in the Diff buffer (@pxref{Useless Whitespace}). Diff |
| 1476 | mode buffers are set up so that Whitespace mode avoids highlighting |
| 1477 | trailing whitespace occurring in the diff context. |
| 1478 | |
| 1479 | @node Misc File Ops |
| 1480 | @section Miscellaneous File Operations |
| 1481 | |
| 1482 | Emacs has commands for performing many other operations on files. |
| 1483 | All operate on one file; they do not accept wildcard file names. |
| 1484 | |
| 1485 | @findex delete-file |
| 1486 | @cindex deletion (of files) |
| 1487 | @kbd{M-x delete-file} prompts for a file and deletes it. If you are |
| 1488 | deleting many files in one directory, it may be more convenient to use |
| 1489 | Dired rather than @code{delete-file}. @xref{Dired Deletion}. |
| 1490 | |
| 1491 | @cindex trash |
| 1492 | @cindex recycle bin |
| 1493 | @kbd{M-x move-file-to-trash} moves a file into the system |
| 1494 | @dfn{Trash} (or @dfn{Recycle Bin}). This is a facility available on |
| 1495 | most operating systems; files that are moved into the Trash can be |
| 1496 | brought back later if you change your mind. |
| 1497 | |
| 1498 | @vindex delete-by-moving-to-trash |
| 1499 | By default, Emacs deletion commands do @emph{not} use the Trash. To |
| 1500 | use the Trash (when it is available) for common deletion commands, |
| 1501 | change the variable @code{delete-by-moving-to-trash} to @code{t}. |
| 1502 | This affects the commands @kbd{M-x delete-file} and @kbd{M-x |
| 1503 | delete-directory} (@pxref{Directories}), as well as the deletion |
| 1504 | commands in Dired (@pxref{Dired Deletion}). Supplying a prefix |
| 1505 | argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes |
| 1506 | them delete outright, instead of using the Trash, regardless of |
| 1507 | @code{delete-by-moving-to-trash}. |
| 1508 | |
| 1509 | @ifnottex |
| 1510 | If a file is under version control (@pxref{Version Control}), you |
| 1511 | should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x |
| 1512 | delete-file}. @xref{VC Delete/Rename}. |
| 1513 | @end ifnottex |
| 1514 | |
| 1515 | @findex copy-file |
| 1516 | @cindex copying files |
| 1517 | @kbd{M-x copy-file} reads the file @var{old} and writes a new file |
| 1518 | named @var{new} with the same contents. |
| 1519 | |
| 1520 | @findex copy-directory |
| 1521 | @kbd{M-x copy-directory} copies directories, similar to the |
| 1522 | @command{cp -r} shell command. It prompts for a directory @var{old} |
| 1523 | and a destination @var{new}. If @var{new} is an existing directory, |
| 1524 | it creates a copy of the @var{old} directory and puts it in @var{new}. |
| 1525 | If @var{new} is not an existing directory, it copies all the contents |
| 1526 | of @var{old} into a new directory named @var{new}. |
| 1527 | |
| 1528 | @cindex renaming files |
| 1529 | @findex rename-file |
| 1530 | @kbd{M-x rename-file} reads two file names @var{old} and @var{new} |
| 1531 | using the minibuffer, then renames file @var{old} as @var{new}. If |
| 1532 | the file name @var{new} already exists, you must confirm with |
| 1533 | @kbd{yes} or renaming is not done; this is because renaming causes the |
| 1534 | old meaning of the name @var{new} to be lost. If @var{old} and |
| 1535 | @var{new} are on different file systems, the file @var{old} is copied |
| 1536 | and deleted. If the argument @var{new} is just a directory name, the |
| 1537 | real new name is in that directory, with the same non-directory |
| 1538 | component as @var{old}. For example, @kbd{M-x rename-file RET ~/foo |
| 1539 | RET /tmp RET} renames @file{~/foo} to @file{/tmp/foo}. The same rule |
| 1540 | applies to all the remaining commands in this section. All of them |
| 1541 | ask for confirmation when the new file name already exists, too. |
| 1542 | |
| 1543 | @ifnottex |
| 1544 | If a file is under version control (@pxref{Version Control}), you |
| 1545 | should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x |
| 1546 | rename-file}. @xref{VC Delete/Rename}. |
| 1547 | @end ifnottex |
| 1548 | |
| 1549 | @findex add-name-to-file |
| 1550 | @cindex hard links (creation) |
| 1551 | @kbd{M-x add-name-to-file} adds an additional name to an existing |
| 1552 | file without removing its old name. The new name is created as a |
| 1553 | ``hard link'' to the existing file. The new name must belong on the |
| 1554 | same file system that the file is on. On MS-Windows, this command |
| 1555 | works only if the file resides in an NTFS file system. On MS-DOS, it |
| 1556 | works by copying the file. |
| 1557 | |
| 1558 | @findex make-symbolic-link |
| 1559 | @cindex symbolic links (creation) |
| 1560 | @kbd{M-x make-symbolic-link} reads two file names @var{target} and |
| 1561 | @var{linkname}, then creates a symbolic link named @var{linkname}, |
| 1562 | which points at @var{target}. The effect is that future attempts to |
| 1563 | open file @var{linkname} will refer to whatever file is named |
| 1564 | @var{target} at the time the opening is done, or will get an error if |
| 1565 | the name @var{target} is nonexistent at that time. This command does |
| 1566 | not expand the argument @var{target}, so that it allows you to specify |
| 1567 | a relative name as the target of the link. On MS-Windows, this |
| 1568 | command works only on MS Windows Vista and later. |
| 1569 | |
| 1570 | @kindex C-x i |
| 1571 | @findex insert-file |
| 1572 | @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the |
| 1573 | contents of the specified file into the current buffer at point, |
| 1574 | leaving point unchanged before the contents. The position after the |
| 1575 | inserted contents is added to the mark ring, without activating the |
| 1576 | mark (@pxref{Mark Ring}). |
| 1577 | |
| 1578 | @findex insert-file-literally |
| 1579 | @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, |
| 1580 | except the file is inserted ``literally'': it is treated as a sequence |
| 1581 | of @acronym{ASCII} characters with no special encoding or conversion, |
| 1582 | similar to the @kbd{M-x find-file-literally} command |
| 1583 | (@pxref{Visiting}). |
| 1584 | |
| 1585 | @findex write-region |
| 1586 | @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it |
| 1587 | copies the contents of the region into the specified file. @kbd{M-x |
| 1588 | append-to-file} adds the text of the region to the end of the |
| 1589 | specified file. @xref{Accumulating Text}. The variable |
| 1590 | @code{write-region-inhibit-fsync} applies to these commands, as well |
| 1591 | as saving files; see @ref{Customize Save}. |
| 1592 | |
| 1593 | @findex set-file-modes |
| 1594 | @cindex file modes |
| 1595 | @cindex file permissions |
| 1596 | @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file |
| 1597 | mode}, and applies that file mode to the specified file. File modes, |
| 1598 | also called @dfn{file permissions}, determine whether a file can be |
| 1599 | read, written to, or executed, and by whom. This command reads file |
| 1600 | modes using the same symbolic or octal format accepted by the |
| 1601 | @command{chmod} command; for instance, @samp{u+x} means to add |
| 1602 | execution permission for the user who owns the file. It has no effect |
| 1603 | on operating systems that do not support file modes. @code{chmod} is a |
| 1604 | convenience alias for this function. |
| 1605 | |
| 1606 | @node Compressed Files |
| 1607 | @section Accessing Compressed Files |
| 1608 | @cindex compression |
| 1609 | @cindex uncompression |
| 1610 | @cindex Auto Compression mode |
| 1611 | @cindex mode, Auto Compression |
| 1612 | @pindex gzip |
| 1613 | |
| 1614 | Emacs automatically uncompresses compressed files when you visit |
| 1615 | them, and automatically recompresses them if you alter them and save |
| 1616 | them. Emacs recognizes compressed files by their file names. File |
| 1617 | names ending in @samp{.gz} indicate a file compressed with |
| 1618 | @code{gzip}. Other endings indicate other compression programs. |
| 1619 | |
| 1620 | Automatic uncompression and compression apply to all the operations in |
| 1621 | which Emacs uses the contents of a file. This includes visiting it, |
| 1622 | saving it, inserting its contents into a buffer, loading it, and byte |
| 1623 | compiling it. |
| 1624 | |
| 1625 | @findex auto-compression-mode |
| 1626 | @vindex auto-compression-mode |
| 1627 | To disable this feature, type the command @kbd{M-x |
| 1628 | auto-compression-mode}. You can disable it permanently by |
| 1629 | customizing the variable @code{auto-compression-mode}. |
| 1630 | |
| 1631 | @node File Archives |
| 1632 | @section File Archives |
| 1633 | @cindex mode, tar |
| 1634 | @cindex Tar mode |
| 1635 | @cindex file archives |
| 1636 | |
| 1637 | A file whose name ends in @samp{.tar} is normally an @dfn{archive} |
| 1638 | made by the @code{tar} program. Emacs views these files in a special |
| 1639 | mode called Tar mode which provides a Dired-like list of the contents |
| 1640 | (@pxref{Dired}). You can move around through the list just as you |
| 1641 | would in Dired, and visit the subfiles contained in the archive. |
| 1642 | However, not all Dired commands are available in Tar mode. |
| 1643 | |
| 1644 | If Auto Compression mode is enabled (@pxref{Compressed Files}), then |
| 1645 | Tar mode is used also for compressed archives---files with extensions |
| 1646 | @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. |
| 1647 | |
| 1648 | The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file |
| 1649 | into its own buffer. You can edit it there, and if you save the |
| 1650 | buffer, the edited version will replace the version in the Tar buffer. |
| 1651 | Clicking with the mouse on the file name in the Tar buffer does |
| 1652 | likewise. @kbd{v} extracts a file into a buffer in View mode |
| 1653 | (@pxref{View Mode}). @kbd{o} extracts the file and displays it in |
| 1654 | another window, so you could edit the file and operate on the archive |
| 1655 | simultaneously. |
| 1656 | |
| 1657 | @kbd{d} marks a file for deletion when you later use @kbd{x}, and |
| 1658 | @kbd{u} unmarks a file, as in Dired. @kbd{C} copies a file from the |
| 1659 | archive to disk and @kbd{R} renames a file within the archive. |
| 1660 | @kbd{g} reverts the buffer from the archive on disk. The keys |
| 1661 | @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission bits, |
| 1662 | group, and owner, respectively. |
| 1663 | |
| 1664 | Saving the Tar buffer writes a new version of the archive to disk with |
| 1665 | the changes you made to the components. |
| 1666 | |
| 1667 | You don't need the @code{tar} program to use Tar mode---Emacs reads |
| 1668 | the archives directly. However, accessing compressed archives |
| 1669 | requires the appropriate uncompression program. |
| 1670 | |
| 1671 | @cindex Archive mode |
| 1672 | @cindex mode, archive |
| 1673 | @cindex @code{arc} |
| 1674 | @cindex @code{jar} |
| 1675 | @cindex @code{rar} |
| 1676 | @cindex @code{zip} |
| 1677 | @cindex @code{lzh} |
| 1678 | @cindex @code{zoo} |
| 1679 | @cindex @code{7z} |
| 1680 | @pindex arc |
| 1681 | @pindex jar |
| 1682 | @pindex zip |
| 1683 | @pindex rar |
| 1684 | @pindex lzh |
| 1685 | @pindex zoo |
| 1686 | @pindex 7z |
| 1687 | @cindex Java class archives |
| 1688 | @cindex unzip archives |
| 1689 | A separate but similar Archive mode is used for @code{arc}, |
| 1690 | @code{jar}, @code{lzh}, @code{zip}, @code{rar}, @code{7z}, and |
| 1691 | @code{zoo} archives, as well as @code{exe} files that are |
| 1692 | self-extracting executables. |
| 1693 | |
| 1694 | The key bindings of Archive mode are similar to those in Tar mode, |
| 1695 | with the addition of the @kbd{m} key which marks a file for subsequent |
| 1696 | operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. |
| 1697 | Also, the @kbd{a} key toggles the display of detailed file |
| 1698 | information, for those archive types where it won't fit in a single |
| 1699 | line. Operations such as renaming a subfile, or changing its mode or |
| 1700 | owner, are supported only for some of the archive formats. |
| 1701 | |
| 1702 | Unlike Tar mode, Archive mode runs the archiving programs to unpack |
| 1703 | and repack archives. However, you don't need these programs to look |
| 1704 | at the archive table of contents, only to extract or manipulate the |
| 1705 | subfiles in the archive. Details of the program names and their |
| 1706 | options can be set in the @samp{Archive} Customize group. |
| 1707 | |
| 1708 | @node Remote Files |
| 1709 | @section Remote Files |
| 1710 | |
| 1711 | @cindex Tramp |
| 1712 | @cindex FTP |
| 1713 | @cindex remote file access |
| 1714 | You can refer to files on other machines using a special file name |
| 1715 | syntax: |
| 1716 | |
| 1717 | @example |
| 1718 | @group |
| 1719 | /@var{host}:@var{filename} |
| 1720 | /@var{user}@@@var{host}:@var{filename} |
| 1721 | /@var{user}@@@var{host}#@var{port}:@var{filename} |
| 1722 | /@var{method}:@var{user}@@@var{host}:@var{filename} |
| 1723 | /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} |
| 1724 | @end group |
| 1725 | @end example |
| 1726 | |
| 1727 | @noindent |
| 1728 | To carry out this request, Emacs uses a remote-login program such as |
| 1729 | @command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}. |
| 1730 | You can always specify in the file name which method to use---for |
| 1731 | example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, |
| 1732 | whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses |
| 1733 | @command{ssh}. When you don't specify a method in the file name, |
| 1734 | Emacs chooses the method as follows: |
| 1735 | |
| 1736 | @enumerate |
| 1737 | @item |
| 1738 | If the host name starts with @samp{ftp.} (with dot), Emacs uses FTP. |
| 1739 | @item |
| 1740 | If the user name is @samp{ftp} or @samp{anonymous}, Emacs uses FTP. |
| 1741 | @item |
| 1742 | If the variable @code{tramp-default-method} is set to @samp{ftp}, |
| 1743 | Emacs uses FTP. |
| 1744 | @item |
| 1745 | If @command{ssh-agent} is running, Emacs uses @command{scp}. |
| 1746 | @item |
| 1747 | Otherwise, Emacs uses @command{ssh}. |
| 1748 | @end enumerate |
| 1749 | |
| 1750 | @cindex disabling remote files |
| 1751 | @noindent |
| 1752 | You can entirely turn off the remote file name feature by setting the |
| 1753 | variable @code{tramp-mode} to @code{nil}. You can turn off the |
| 1754 | feature in individual cases by quoting the file name with @samp{/:} |
| 1755 | (@pxref{Quoted File Names}). |
| 1756 | |
| 1757 | @cindex ange-ftp |
| 1758 | Remote file access through FTP is handled by the Ange-FTP package, which |
| 1759 | is documented in the following. Remote file access through the other |
| 1760 | methods is handled by the Tramp package, which has its own manual. |
| 1761 | @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. |
| 1762 | |
| 1763 | @vindex ange-ftp-default-user |
| 1764 | @cindex user name for remote file access |
| 1765 | When the Ange-FTP package is used, Emacs logs in through FTP using |
| 1766 | the name @var{user}, if that is specified in the remote file name. If |
| 1767 | @var{user} is unspecified, Emacs logs in using your user name on the |
| 1768 | local system; but if you set the variable @code{ange-ftp-default-user} |
| 1769 | to a string, that string is used instead. When logging in, Emacs may |
| 1770 | also ask for a password. |
| 1771 | |
| 1772 | @cindex backups for remote files |
| 1773 | @vindex ange-ftp-make-backup-files |
| 1774 | For performance reasons, Emacs does not make backup files for files |
| 1775 | accessed via FTP by default. To make it do so, change the variable |
| 1776 | @code{ange-ftp-make-backup-files} to a non-@code{nil} value. |
| 1777 | |
| 1778 | By default, auto-save files for remote files are made in the |
| 1779 | temporary file directory on the local machine, as specified by the |
| 1780 | variable @code{auto-save-file-name-transforms}. @xref{Auto Save |
| 1781 | Files}. |
| 1782 | |
| 1783 | @cindex anonymous FTP |
| 1784 | @vindex ange-ftp-generate-anonymous-password |
| 1785 | To visit files accessible by anonymous FTP, you use special user |
| 1786 | names @samp{anonymous} or @samp{ftp}. Passwords for these user names |
| 1787 | are handled specially. The variable |
| 1788 | @code{ange-ftp-generate-anonymous-password} controls what happens: if |
| 1789 | the value of this variable is a string, then that string is used as |
| 1790 | the password; if non-@code{nil} (the default), then the value of |
| 1791 | @code{user-mail-address} is used; if @code{nil}, then Emacs prompts |
| 1792 | you for a password as usual (@pxref{Passwords}). |
| 1793 | |
| 1794 | @cindex firewall, and accessing remote files |
| 1795 | @cindex gateway, and remote file access with @code{ange-ftp} |
| 1796 | @vindex ange-ftp-smart-gateway |
| 1797 | @vindex ange-ftp-gateway-host |
| 1798 | Sometimes you may be unable to access files on a remote machine |
| 1799 | because a @dfn{firewall} in between blocks the connection for security |
| 1800 | reasons. If you can log in on a @dfn{gateway} machine from which the |
| 1801 | target files @emph{are} accessible, and whose FTP server supports |
| 1802 | gatewaying features, you can still use remote file names; all you have |
| 1803 | to do is specify the name of the gateway machine by setting the |
| 1804 | variable @code{ange-ftp-gateway-host}, and set |
| 1805 | @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able |
| 1806 | to make remote file names work, but the procedure is complex. You can |
| 1807 | read the instructions by typing @kbd{M-x finder-commentary @key{RET} |
| 1808 | ange-ftp @key{RET}}. |
| 1809 | |
| 1810 | @node Quoted File Names |
| 1811 | @section Quoted File Names |
| 1812 | |
| 1813 | @cindex quoting file names |
| 1814 | @cindex file names, quote special characters |
| 1815 | You can @dfn{quote} an absolute file name to prevent special |
| 1816 | characters and syntax in it from having their special effects. |
| 1817 | The way to do this is to add @samp{/:} at the beginning. |
| 1818 | |
| 1819 | For example, you can quote a local file name which appears remote, to |
| 1820 | prevent it from being treated as a remote file name. Thus, if you have |
| 1821 | a directory named @file{/foo:} and a file named @file{bar} in it, you |
| 1822 | can refer to that file in Emacs as @samp{/:/foo:/bar}. |
| 1823 | |
| 1824 | @samp{/:} can also prevent @samp{~} from being treated as a special |
| 1825 | character for a user's home directory. For example, @file{/:/tmp/~hack} |
| 1826 | refers to a file whose name is @file{~hack} in directory @file{/tmp}. |
| 1827 | |
| 1828 | Quoting with @samp{/:} is also a way to enter in the minibuffer a |
| 1829 | file name that contains @samp{$}. In order for this to work, the |
| 1830 | @samp{/:} must be at the beginning of the minibuffer contents. (You |
| 1831 | can also double each @samp{$}; see @ref{File Names with $}.) |
| 1832 | |
| 1833 | You can also quote wildcard characters with @samp{/:}, for visiting. |
| 1834 | For example, @file{/:/tmp/foo*bar} visits the file |
| 1835 | @file{/tmp/foo*bar}. |
| 1836 | |
| 1837 | Another method of getting the same result is to enter |
| 1838 | @file{/tmp/foo[*]bar}, which is a wildcard specification that matches |
| 1839 | only @file{/tmp/foo*bar}. However, in many cases there is no need to |
| 1840 | quote the wildcard characters because even unquoted they give the |
| 1841 | right result. For example, if the only file name in @file{/tmp} that |
| 1842 | starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, |
| 1843 | then specifying @file{/tmp/foo*bar} will visit only |
| 1844 | @file{/tmp/foo*bar}. |
| 1845 | |
| 1846 | @node File Name Cache |
| 1847 | @section File Name Cache |
| 1848 | |
| 1849 | @cindex file name caching |
| 1850 | @cindex cache of file names |
| 1851 | @pindex find |
| 1852 | @kindex C-TAB |
| 1853 | @findex file-cache-minibuffer-complete |
| 1854 | You can use the @dfn{file name cache} to make it easy to locate a |
| 1855 | file by name, without having to remember exactly where it is located. |
| 1856 | When typing a file name in the minibuffer, @kbd{C-@key{tab}} |
| 1857 | (@code{file-cache-minibuffer-complete}) completes it using the file |
| 1858 | name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the |
| 1859 | possible completions of what you had originally typed. (However, note |
| 1860 | that the @kbd{C-@key{tab}} character cannot be typed on most text |
| 1861 | terminals.) |
| 1862 | |
| 1863 | The file name cache does not fill up automatically. Instead, you |
| 1864 | load file names into the cache using these commands: |
| 1865 | |
| 1866 | @findex file-cache-add-directory |
| 1867 | @table @kbd |
| 1868 | @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} |
| 1869 | Add each file name in @var{directory} to the file name cache. |
| 1870 | @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} |
| 1871 | Add each file name in @var{directory} and all of its nested |
| 1872 | subdirectories to the file name cache. |
| 1873 | @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} |
| 1874 | Add each file name in @var{directory} and all of its nested |
| 1875 | subdirectories to the file name cache, using @command{locate} to find |
| 1876 | them all. |
| 1877 | @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} |
| 1878 | Add each file name in each directory listed in @var{variable} to the |
| 1879 | file name cache. @var{variable} should be a Lisp variable whose value |
| 1880 | is a list of directory names, like @code{load-path}. |
| 1881 | @item M-x file-cache-clear-cache @key{RET} |
| 1882 | Clear the cache; that is, remove all file names from it. |
| 1883 | @end table |
| 1884 | |
| 1885 | The file name cache is not persistent: it is kept and maintained |
| 1886 | only for the duration of the Emacs session. You can view the contents |
| 1887 | of the cache with the @code{file-cache-display} command. |
| 1888 | |
| 1889 | @node File Conveniences |
| 1890 | @section Convenience Features for Finding Files |
| 1891 | |
| 1892 | In this section, we introduce some convenient facilities for finding |
| 1893 | recently-opened files, reading file names from a buffer, and viewing |
| 1894 | image files. |
| 1895 | |
| 1896 | @findex recentf-mode |
| 1897 | @vindex recentf-mode |
| 1898 | @findex recentf-save-list |
| 1899 | @findex recentf-edit-list |
| 1900 | If you enable Recentf mode, with @kbd{M-x recentf-mode}, the |
| 1901 | @samp{File} menu includes a submenu containing a list of recently |
| 1902 | opened files. @kbd{M-x recentf-save-list} saves the current |
| 1903 | @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} |
| 1904 | edits it. |
| 1905 | |
| 1906 | The @kbd{M-x ffap} command generalizes @code{find-file} with more |
| 1907 | powerful heuristic defaults (@pxref{FFAP}), often based on the text at |
| 1908 | point. Partial Completion mode offers other features extending |
| 1909 | @code{find-file}, which can be used with @code{ffap}. |
| 1910 | @xref{Completion Options}. |
| 1911 | |
| 1912 | @findex image-mode |
| 1913 | @findex image-toggle-display |
| 1914 | @findex image-toggle-animation |
| 1915 | @cindex images, viewing |
| 1916 | @cindex image animation |
| 1917 | @cindex animated images |
| 1918 | Visiting image files automatically selects Image mode. In this |
| 1919 | major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display}) |
| 1920 | to toggle between displaying the file as an image in the Emacs buffer, |
| 1921 | and displaying its underlying text (or raw byte) representation. |
| 1922 | Displaying the file as an image works only if Emacs is compiled with |
| 1923 | support for displaying such images. If the displayed image is wider |
| 1924 | or taller than the frame, the usual point motion keys (@kbd{C-f}, |
| 1925 | @kbd{C-p}, and so forth) cause different parts of the image to be |
| 1926 | displayed. If the image can be animated, the command @kbd{RET} |
| 1927 | (@code{image-toggle-animation}) starts or stops the animation. |
| 1928 | Animation plays once, unless the option @code{image-animate-loop} is |
| 1929 | non-@code{nil}. Currently, Emacs only supports animation in GIF |
| 1930 | files. |
| 1931 | |
| 1932 | @cindex ImageMagick support |
| 1933 | @vindex imagemagick-enabled-types |
| 1934 | @vindex imagemagick-types-inhibit |
| 1935 | If Emacs was compiled with support for the ImageMagick library, it |
| 1936 | can use ImageMagick to render a wide variety of images. The variable |
| 1937 | @code{imagemagick-enabled-types} lists the image types that Emacs may |
| 1938 | render using ImageMagick; each element in the list should be an |
| 1939 | internal ImageMagick name for an image type, as a symbol or an |
| 1940 | equivalent string (e.g.@: @code{BMP} for @file{.bmp} images). To |
| 1941 | enable ImageMagick for all possible image types, change |
| 1942 | @code{imagemagick-enabled-types} to @code{t}. The variable |
| 1943 | @code{imagemagick-types-inhibit} lists the image types which should |
| 1944 | never be rendered using ImageMagick, regardless of the value of |
| 1945 | @code{imagemagick-enabled-types} (the default list includes types like |
| 1946 | @code{C} and @code{HTML}, which ImageMagick can render as an ``image'' |
| 1947 | but Emacs should not). To disable ImageMagick entirely, change |
| 1948 | @code{imagemagick-types-inhibit} to @code{t}. |
| 1949 | |
| 1950 | @findex thumbs-mode |
| 1951 | @findex mode, thumbs |
| 1952 | The Image-Dired package can also be used to view images as |
| 1953 | thumbnails. @xref{Image-Dired}. |
| 1954 | |
| 1955 | @node Filesets |
| 1956 | @section Filesets |
| 1957 | @cindex filesets |
| 1958 | |
| 1959 | @findex filesets-init |
| 1960 | If you regularly edit a certain group of files, you can define them |
| 1961 | as a @dfn{fileset}. This lets you perform certain operations, such as |
| 1962 | visiting, @code{query-replace}, and shell commands on all the files at |
| 1963 | once. To make use of filesets, you must first add the expression |
| 1964 | @code{(filesets-init)} to your init file (@pxref{Init File}). This |
| 1965 | adds a @samp{Filesets} menu to the menu bar. |
| 1966 | |
| 1967 | @findex filesets-add-buffer |
| 1968 | @findex filesets-remove-buffer |
| 1969 | The simplest way to define a fileset is by adding files to it one at |
| 1970 | a time. To add a file to fileset @var{name}, visit the file and type |
| 1971 | @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If |
| 1972 | there is no fileset @var{name}, this creates a new one, which |
| 1973 | initially contains only the current file. The command @kbd{M-x |
| 1974 | filesets-remove-buffer} removes the current file from a fileset. |
| 1975 | |
| 1976 | You can also edit the list of filesets directly, with @kbd{M-x |
| 1977 | filesets-edit} (or by choosing @samp{Edit Filesets} from the |
| 1978 | @samp{Filesets} menu). The editing is performed in a Customize buffer |
| 1979 | (@pxref{Easy Customization}). Normally, a fileset is a simple list of |
| 1980 | files, but you can also define a fileset as a regular expression |
| 1981 | matching file names. Some examples of these more complicated filesets |
| 1982 | are shown in the Customize buffer. Remember to select @samp{Save for |
| 1983 | future sessions} if you want to use the same filesets in future Emacs |
| 1984 | sessions. |
| 1985 | |
| 1986 | You can use the command @kbd{M-x filesets-open} to visit all the |
| 1987 | files in a fileset, and @kbd{M-x filesets-close} to close them. Use |
| 1988 | @kbd{M-x filesets-run-cmd} to run a shell command on all the files in |
| 1989 | a fileset. These commands are also available from the @samp{Filesets} |
| 1990 | menu, where each existing fileset is represented by a submenu. |
| 1991 | |
| 1992 | @xref{Version Control}, for a different concept of ``filesets'': |
| 1993 | groups of files bundled together for version control operations. |
| 1994 | Filesets of that type are unnamed, and do not persist across Emacs |
| 1995 | sessions. |