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