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