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