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