Mercurial > emacs
annotate man/files.texi @ 36157:f079e00e119f
The log entry for the previous version was a spazz. Ignore it.
New node Cursor Display. Put x-stretch-cursor there.
Put "busy cursor" stuff in Display Custom node.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sat, 17 Feb 2001 17:23:54 +0000 |
parents | 3594ca3f5f64 |
children | 62cf166239f3 |
rev | line source |
---|---|
25829 | 1 @c This is part of the Emacs manual. |
28123
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2 @c Copyright (C) 1985,86,87,93,94,95,97,99, 2000 Free Software Foundation, Inc. |
25829 | 3 @c See file emacs.texi for copying conditions. |
4 @node Files, Buffers, Fixit, Top | |
5 @chapter File Handling | |
6 @cindex files | |
7 | |
8 The operating system stores data permanently in named @dfn{files}. So | |
9 most of the text you edit with Emacs comes from a file and is ultimately | |
10 stored in a file. | |
11 | |
12 To edit a file, you must tell Emacs to read the file and prepare a | |
13 buffer containing a copy of the file's text. This is called | |
14 @dfn{visiting} the file. Editing commands apply directly to text in the | |
15 buffer; that is, to the copy inside Emacs. Your changes appear in the | |
16 file itself only when you @dfn{save} the buffer back into the file. | |
17 | |
18 In addition to visiting and saving files, Emacs can delete, copy, | |
19 rename, and append to files, keep multiple versions of them, and operate | |
20 on file directories. | |
21 | |
22 @menu | |
23 * File Names:: How to type and edit file-name arguments. | |
24 * Visiting:: Visiting a file prepares Emacs to edit the file. | |
25 * Saving:: Saving makes your changes permanent. | |
26 * Reverting:: Reverting cancels all the changes not saved. | |
27 * Auto Save:: Auto Save periodically protects against loss of data. | |
28 * File Aliases:: Handling multiple names for one file. | |
29 * Version Control:: Version control systems (RCS, CVS and SCCS). | |
30 * Directories:: Creating, deleting, and listing file directories. | |
31 * Comparing Files:: Finding where two files differ. | |
32 * Misc File Ops:: Other things you can do on files. | |
33 * Compressed Files:: Accessing compressed files. | |
28123
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
34 * File Archives:: Operating on tar, zip, jar etc. archive files. |
25829 | 35 * Remote Files:: Accessing files on other sites. |
36 * Quoted File Names:: Quoting special characters in file names. | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
37 * File Name Cache:: Completion against a list of files you often use. |
28526
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
38 * File Conveniences:: Convenience Features for Finding Files. |
25829 | 39 @end menu |
40 | |
41 @node File Names | |
42 @section File Names | |
43 @cindex file names | |
44 | |
45 Most Emacs commands that operate on a file require you to specify the | |
46 file name. (Saving and reverting are exceptions; the buffer knows which | |
47 file name to use for them.) You enter the file name using the | |
48 minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available, to make | |
49 it easier to specify long file names. @xref{Completion}. | |
50 | |
51 For most operations, there is a @dfn{default file name} which is used | |
52 if you type just @key{RET} to enter an empty argument. Normally the | |
53 default file name is the name of the file visited in the current buffer; | |
54 this makes it easy to operate on that file with any of the Emacs file | |
55 commands. | |
56 | |
57 @vindex default-directory | |
58 Each buffer has a default directory, normally the same as the | |
59 directory of the file visited in that buffer. When you enter a file | |
60 name without a directory, the default directory is used. If you specify | |
61 a directory in a relative fashion, with a name that does not start with | |
62 a slash, it is interpreted with respect to the default directory. The | |
63 default directory is kept in the variable @code{default-directory}, | |
64 which has a separate value in every buffer. | |
65 | |
66 For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then | |
67 the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo}, | |
68 which does not specify a directory, it is short for @file{/u/rms/gnu/foo}. | |
69 @samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo} | |
70 would stand for the file name @file{/u/rms/gnu/new/foo}. | |
71 | |
72 @findex cd | |
73 @findex pwd | |
74 The command @kbd{M-x pwd} prints the current buffer's default | |
75 directory, and the command @kbd{M-x cd} sets it (to a value read using | |
76 the minibuffer). A buffer's default directory changes only when the | |
77 @code{cd} command is used. A file-visiting buffer's default directory | |
78 is initialized to the directory of the file that is visited there. If | |
79 you create a buffer with @kbd{C-x b}, its default directory is copied | |
80 from that of the buffer that was current at the time. | |
81 | |
82 @vindex insert-default-directory | |
83 The default directory actually appears in the minibuffer when the | |
84 minibuffer becomes active to read a file name. This serves two | |
85 purposes: it @emph{shows} you what the default is, so that you can type | |
86 a relative file name and know with certainty what it will mean, and it | |
87 allows you to @emph{edit} the default to specify a different directory. | |
88 This insertion of the default directory is inhibited if the variable | |
89 @code{insert-default-directory} is set to @code{nil}. | |
90 | |
91 Note that it is legitimate to type an absolute file name after you | |
92 enter the minibuffer, ignoring the presence of the default directory | |
93 name as part of the text. The final minibuffer contents may look | |
94 invalid, but that is not so. For example, if the minibuffer starts out | |
95 with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get | |
96 @samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the | |
97 first slash in the double slash; the result is @samp{/x1/rms/foo}. | |
98 @xref{Minibuffer File}. | |
99 | |
100 @samp{$} in a file name is used to substitute environment variables. | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
101 For example, if you have used the shell command @command{export |
29107 | 102 FOO=rms/hacks} to set up an environment variable named @env{FOO}, then |
25829 | 103 you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an |
104 abbreviation for @file{/u/rms/hacks/test.c}. The environment variable | |
105 name consists of all the alphanumeric characters after the @samp{$}; | |
106 alternatively, it may be enclosed in braces after the @samp{$}. Note | |
107 that shell commands to set environment variables affect Emacs only if | |
108 done before Emacs is started. | |
109 | |
110 To access a file with @samp{$} in its name, type @samp{$$}. This pair | |
111 is converted to a single @samp{$} at the same time as variable | |
112 substitution is performed for single @samp{$}. Alternatively, quote the | |
113 whole file name with @samp{/:} (@pxref{Quoted File Names}). | |
114 | |
115 @findex substitute-in-file-name | |
116 The Lisp function that performs the substitution is called | |
117 @code{substitute-in-file-name}. The substitution is performed only on | |
118 file names read as such using the minibuffer. | |
119 | |
120 You can include non-ASCII characters in file names if you set the | |
121 variable @code{file-name-coding-system} to a non-@code{nil} value. | |
122 @xref{Specify Coding}. | |
123 | |
124 @node Visiting | |
125 @section Visiting Files | |
126 @cindex visiting files | |
127 | |
128 @c WideCommands | |
129 @table @kbd | |
130 @item C-x C-f | |
131 Visit a file (@code{find-file}). | |
132 @item C-x C-r | |
133 Visit a file for viewing, without allowing changes to it | |
134 (@code{find-file-read-only}). | |
135 @item C-x C-v | |
136 Visit a different file instead of the one visited last | |
137 (@code{find-alternate-file}). | |
138 @item C-x 4 f | |
139 Visit a file, in another window (@code{find-file-other-window}). Don't | |
140 alter what is displayed in the selected window. | |
141 @item C-x 5 f | |
142 Visit a file, in a new frame (@code{find-file-other-frame}). Don't | |
143 alter what is displayed in the selected frame. | |
144 @item M-x find-file-literally | |
145 Visit a file with no conversion of the contents. | |
146 @end table | |
147 | |
148 @cindex files, visiting and saving | |
149 @cindex visiting files | |
150 @cindex saving files | |
151 @dfn{Visiting} a file means copying its contents into an Emacs buffer | |
152 so you can edit them. Emacs makes a new buffer for each file that you | |
153 visit. We say that this buffer is visiting the file that it was created | |
154 to hold. Emacs constructs the buffer name from the file name by | |
155 throwing away the directory, keeping just the name proper. For example, | |
156 a file named @file{/usr/rms/emacs.tex} would get a buffer named | |
157 @samp{emacs.tex}. If there is already a buffer with that name, a unique | |
158 name is constructed by appending @samp{<2>}, @samp{<3>}, or so on, using | |
159 the lowest number that makes a name that is not already in use. | |
160 | |
161 Each window's mode line shows the name of the buffer that is being displayed | |
162 in that window, so you can always tell what buffer you are editing. | |
163 | |
164 The changes you make with editing commands are made in the Emacs | |
165 buffer. They do not take effect in the file that you visited, or any | |
166 place permanent, until you @dfn{save} the buffer. Saving the buffer | |
167 means that Emacs writes the current contents of the buffer into its | |
168 visited file. @xref{Saving}. | |
169 | |
170 @cindex modified (buffer) | |
171 If a buffer contains changes that have not been saved, we say the | |
172 buffer is @dfn{modified}. This is important because it implies that | |
173 some changes will be lost if the buffer is not saved. The mode line | |
174 displays two stars near the left margin to indicate that the buffer is | |
175 modified. | |
176 | |
177 @kindex C-x C-f | |
178 @findex find-file | |
179 To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow | |
180 the command with the name of the file you wish to visit, terminated by a | |
181 @key{RET}. | |
182 | |
183 The file name is read using the minibuffer (@pxref{Minibuffer}), with | |
184 defaulting and completion in the standard manner (@pxref{File Names}). | |
185 While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}. | |
186 | |
35647
d1a5bb6d3811
(Visiting): Document the file selection dialog popped by C-x C-f.
Eli Zaretskii <eliz@gnu.org>
parents:
35620
diff
changeset
|
187 @cindex file selection dialog |
d1a5bb6d3811
(Visiting): Document the file selection dialog popped by C-x C-f.
Eli Zaretskii <eliz@gnu.org>
parents:
35620
diff
changeset
|
188 When Emacs is built with a suitable GUI toolkit, it pops up the |
d1a5bb6d3811
(Visiting): Document the file selection dialog popped by C-x C-f.
Eli Zaretskii <eliz@gnu.org>
parents:
35620
diff
changeset
|
189 standard File Selection dialog of that toolkit instead of prompting for |
d1a5bb6d3811
(Visiting): Document the file selection dialog popped by C-x C-f.
Eli Zaretskii <eliz@gnu.org>
parents:
35620
diff
changeset
|
190 the file name in the minibuffer. On Unix and GNU/Linux platforms, Emacs |
d1a5bb6d3811
(Visiting): Document the file selection dialog popped by C-x C-f.
Eli Zaretskii <eliz@gnu.org>
parents:
35620
diff
changeset
|
191 does that when built with LessTif and Motif toolkits; on MS-Windows, the |
d1a5bb6d3811
(Visiting): Document the file selection dialog popped by C-x C-f.
Eli Zaretskii <eliz@gnu.org>
parents:
35620
diff
changeset
|
192 GUI version does that by default. |
d1a5bb6d3811
(Visiting): Document the file selection dialog popped by C-x C-f.
Eli Zaretskii <eliz@gnu.org>
parents:
35620
diff
changeset
|
193 |
25829 | 194 Your confirmation that @kbd{C-x C-f} has completed successfully is the |
195 appearance of new text on the screen and a new buffer name in the mode | |
196 line. If the specified file does not exist and could not be created, or | |
197 cannot be read, then you get an error, with an error message displayed | |
198 in the echo area. | |
199 | |
200 If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make | |
201 another copy. It selects the existing buffer containing that file. | |
202 However, before doing so, it checks that the file itself has not changed | |
203 since you visited or saved it last. If the file has changed, a warning | |
204 message is printed. @xref{Interlocking,,Simultaneous Editing}. | |
205 | |
206 @cindex creating files | |
207 What if you want to create a new file? Just visit it. Emacs prints | |
208 @samp{(New File)} in the echo area, but in other respects behaves as if | |
209 you had visited an existing empty file. If you make any changes and | |
210 save them, the file is created. | |
211 | |
212 Emacs recognizes from the contents of a file which convention it uses | |
213 to separate lines---newline (used on GNU/Linux and on Unix), | |
214 carriage-return linefeed (used on Microsoft systems), or just | |
215 carriage-return (used on the Macintosh)---and automatically converts the | |
216 contents to the normal Emacs convention, which is that the newline | |
217 character separates lines. This is a part of the general feature of | |
218 coding system conversion (@pxref{Coding Systems}), and makes it possible | |
219 to edit files imported from various different operating systems with | |
220 equal convenience. If you change the text and save the file, Emacs | |
221 performs the inverse conversion, changing newlines back into | |
222 carriage-return linefeed or just carriage-return if appropriate. | |
223 | |
224 @vindex find-file-run-dired | |
225 If the file you specify is actually a directory, @kbd{C-x C-f} invokes | |
226 Dired, the Emacs directory browser, so that you can ``edit'' the contents | |
227 of the directory (@pxref{Dired}). Dired is a convenient way to delete, | |
228 look at, or operate on the files in the directory. However, if the | |
229 variable @code{find-file-run-dired} is @code{nil}, then it is an error | |
230 to try to visit a directory. | |
231 | |
28327
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
232 @cindex wildcard characters in file names |
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
233 @vindex find-file-wildcards |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
234 If the file name you specify contains shell-style wildcard |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
235 characters, Emacs visits all the files that match it. Wildcards |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
236 comprise @samp{?}, @samp{*} and @samp{[@dots{}]} sequences. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
237 @xref{Quoted File Names}, for how to visit a file whose name actually |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
238 contains wildcard characters. You can disable the wildcard feature by |
28327
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
239 customizing @code{find-file-wildcards}. |
25829 | 240 |
241 If you visit a file that the operating system won't let you modify, | |
242 Emacs makes the buffer read-only, so that you won't go ahead and make | |
243 changes that you'll have trouble saving afterward. You can make the | |
244 buffer writable with @kbd{C-x C-q} (@code{vc-toggle-read-only}). | |
245 @xref{Misc Buffer}. | |
246 | |
247 @kindex C-x C-r | |
248 @findex find-file-read-only | |
249 Occasionally you might want to visit a file as read-only in order to | |
250 protect yourself from entering changes accidentally; do so by visiting | |
251 the file with the command @kbd{C-x C-r} (@code{find-file-read-only}). | |
252 | |
253 @kindex C-x C-v | |
254 @findex find-alternate-file | |
255 If you visit a nonexistent file unintentionally (because you typed the | |
256 wrong file name), use the @kbd{C-x C-v} command | |
257 (@code{find-alternate-file}) to visit the file you really wanted. | |
258 @kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current | |
259 buffer (after first offering to save it if it is modified). When it | |
260 reads the file name to visit, it inserts the entire default file name in | |
261 the buffer, with point just after the directory part; this is convenient | |
262 if you made a slight error in typing the name. | |
263 | |
264 If you find a file which exists but cannot be read, @kbd{C-x C-f} | |
265 signals an error. | |
266 | |
267 @kindex C-x 4 f | |
268 @findex find-file-other-window | |
269 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} | |
270 except that the buffer containing the specified file is selected in another | |
271 window. The window that was selected before @kbd{C-x 4 f} continues to | |
272 show the same buffer it was already showing. If this command is used when | |
273 only one window is being displayed, that window is split in two, with one | |
274 window showing the same buffer as before, and the other one showing the | |
275 newly requested file. @xref{Windows}. | |
276 | |
277 @kindex C-x 5 f | |
278 @findex find-file-other-frame | |
279 @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a | |
280 new frame, or makes visible any existing frame showing the file you | |
281 seek. This feature is available only when you are using a window | |
282 system. @xref{Frames}. | |
283 | |
284 @findex find-file-literally | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
285 If you wish to edit a file as a sequence of ASCII characters with no special |
25829 | 286 encoding or conversion, use the @kbd{M-x find-file-literally} command. |
287 It visits a file, like @kbd{C-x C-f}, but does not do format conversion | |
288 (@pxref{Formatted Text}), character code conversion (@pxref{Coding | |
33559 | 289 Systems}), or automatic uncompression (@pxref{Compressed Files}), and |
290 does not add a final newline because of @code{require-final-newline}. | |
25829 | 291 If you already have visited the same file in the usual (non-literal) |
292 manner, this command asks you whether to visit it literally instead. | |
293 | |
294 @vindex find-file-hooks | |
295 @vindex find-file-not-found-hooks | |
296 Two special hook variables allow extensions to modify the operation of | |
297 visiting files. Visiting a file that does not exist runs the functions | |
298 in the list @code{find-file-not-found-hooks}; this variable holds a list | |
299 of functions, and the functions are called one by one (with no | |
300 arguments) until one of them returns non-@code{nil}. This is not a | |
301 normal hook, and the name ends in @samp{-hooks} rather than @samp{-hook} | |
302 to indicate that fact. | |
303 | |
304 Any visiting of a file, whether extant or not, expects | |
305 @code{find-file-hooks} to contain a list of functions, and calls them | |
306 all, one by one, with no arguments. This variable is really a normal | |
307 hook, but it has an abnormal name for historical compatibility. In the | |
308 case of a nonexistent file, the @code{find-file-not-found-hooks} are run | |
309 first. @xref{Hooks}. | |
310 | |
311 There are several ways to specify automatically the major mode for | |
312 editing the file (@pxref{Choosing Modes}), and to specify local | |
313 variables defined for that file (@pxref{File Variables}). | |
314 | |
315 @node Saving | |
316 @section Saving Files | |
317 | |
318 @dfn{Saving} a buffer in Emacs means writing its contents back into the file | |
319 that was visited in the buffer. | |
320 | |
321 @table @kbd | |
322 @item C-x C-s | |
323 Save the current buffer in its visited file (@code{save-buffer}). | |
324 @item C-x s | |
325 Save any or all buffers in their visited files (@code{save-some-buffers}). | |
326 @item M-~ | |
327 Forget that the current buffer has been changed (@code{not-modified}). | |
29556 | 328 With prefix argument (@kbd{C-u}), mark the current buffer as changed. |
25829 | 329 @item C-x C-w |
330 Save the current buffer in a specified file (@code{write-file}). | |
331 @item M-x set-visited-file-name | |
332 Change file the name under which the current buffer will be saved. | |
333 @end table | |
334 | |
335 @kindex C-x C-s | |
336 @findex save-buffer | |
337 When you wish to save the file and make your changes permanent, type | |
338 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} | |
339 displays a message like this: | |
340 | |
341 @example | |
342 Wrote /u/rms/gnu/gnu.tasks | |
343 @end example | |
344 | |
345 @noindent | |
346 If the selected buffer is not modified (no changes have been made in it | |
347 since the buffer was created or last saved), saving is not really done, | |
348 because it would have no effect. Instead, @kbd{C-x C-s} displays a message | |
349 like this in the echo area: | |
350 | |
351 @example | |
352 (No changes need to be saved) | |
353 @end example | |
354 | |
355 @kindex C-x s | |
356 @findex save-some-buffers | |
357 The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any | |
358 or all modified buffers. It asks you what to do with each buffer. The | |
359 possible responses are analogous to those of @code{query-replace}: | |
360 | |
361 @table @kbd | |
362 @item y | |
363 Save this buffer and ask about the rest of the buffers. | |
364 @item n | |
365 Don't save this buffer, but ask about the rest of the buffers. | |
366 @item ! | |
367 Save this buffer and all the rest with no more questions. | |
368 @c following generates acceptable underfull hbox | |
369 @item @key{RET} | |
370 Terminate @code{save-some-buffers} without any more saving. | |
371 @item . | |
372 Save this buffer, then exit @code{save-some-buffers} without even asking | |
373 about other buffers. | |
374 @item C-r | |
375 View the buffer that you are currently being asked about. When you exit | |
376 View mode, you get back to @code{save-some-buffers}, which asks the | |
377 question again. | |
378 @item C-h | |
379 Display a help message about these options. | |
380 @end table | |
381 | |
382 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes | |
383 @code{save-some-buffers} and therefore asks the same questions. | |
384 | |
385 @kindex M-~ | |
386 @findex not-modified | |
387 If you have changed a buffer but you do not want to save the changes, | |
388 you should take some action to prevent it. Otherwise, each time you use | |
389 @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by | |
390 mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}), | |
391 which clears out the indication that the buffer is modified. If you do | |
392 this, none of the save commands will believe that the buffer needs to be | |
393 saved. (@samp{~} is often used as a mathematical symbol for `not'; thus | |
394 @kbd{M-~} is `not', metafied.) You could also use | |
395 @code{set-visited-file-name} (see below) to mark the buffer as visiting | |
396 a different file name, one which is not in use for anything important. | |
397 Alternatively, you can cancel all the changes made since the file was | |
398 visited or saved, by reading the text from the file again. This is | |
399 called @dfn{reverting}. @xref{Reverting}. You could also undo all the | |
400 changes by repeating the undo command @kbd{C-x u} until you have undone | |
401 all the changes; but reverting is easier. | |
402 | |
403 @findex set-visited-file-name | |
404 @kbd{M-x set-visited-file-name} alters the name of the file that the | |
405 current buffer is visiting. It reads the new file name using the | |
406 minibuffer. Then it specifies the visited file name and changes the | |
407 buffer name correspondingly (as long as the new name is not in use). | |
408 @code{set-visited-file-name} does not save the buffer in the newly | |
409 visited file; it just alters the records inside Emacs in case you do | |
410 save later. It also marks the buffer as ``modified'' so that @kbd{C-x | |
411 C-s} in that buffer @emph{will} save. | |
412 | |
413 @kindex C-x C-w | |
414 @findex write-file | |
415 If you wish to mark the buffer as visiting a different file and save it | |
416 right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely | |
417 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}. | |
418 @kbd{C-x C-s} used on a buffer that is not visiting a file has the | |
419 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the | |
420 buffer as visiting that file, and saves it there. The default file name in | |
421 a buffer that is not visiting a file is made by combining the buffer name | |
422 with the buffer's default directory. | |
423 | |
424 If the new file name implies a major mode, then @kbd{C-x C-w} switches | |
425 to that major mode, in most cases. The command | |
426 @code{set-visited-file-name} also does this. @xref{Choosing Modes}. | |
427 | |
428 If Emacs is about to save a file and sees that the date of the latest | |
429 version on disk does not match what Emacs last read or wrote, Emacs | |
430 notifies you of this fact, because it probably indicates a problem caused | |
431 by simultaneous editing and requires your immediate attention. | |
432 @xref{Interlocking,, Simultaneous Editing}. | |
433 | |
434 @vindex require-final-newline | |
435 If the variable @code{require-final-newline} is non-@code{nil}, Emacs | |
436 puts a newline at the end of any file that doesn't already end in one, | |
437 every time a file is saved or written. The default is @code{nil}. | |
438 | |
439 @menu | |
440 * Backup:: How Emacs saves the old version of your file. | |
441 * Interlocking:: How Emacs protects against simultaneous editing | |
442 of one file by two users. | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
443 * Shadowing: File Shadowing. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
444 Copying files to `shadows' automatically. |
35524 | 445 * Time Stamps:: Emacs can update time stamps on saved files. |
25829 | 446 @end menu |
447 | |
448 @node Backup | |
449 @subsection Backup Files | |
450 @cindex backup file | |
451 @vindex make-backup-files | |
452 @vindex vc-make-backup-files | |
453 | |
454 On most operating systems, rewriting a file automatically destroys all | |
455 record of what the file used to contain. Thus, saving a file from Emacs | |
456 throws away the old contents of the file---or it would, except that | |
457 Emacs carefully copies the old contents to another file, called the | |
458 @dfn{backup} file, before actually saving. | |
459 | |
460 For most files, the variable @code{make-backup-files} determines | |
461 whether to make backup files. On most operating systems, its default | |
462 value is @code{t}, so that Emacs does write backup files. | |
463 | |
464 For files managed by a version control system (@pxref{Version | |
465 Control}), the variable @code{vc-make-backup-files} determines whether | |
466 to make backup files. By default, it is @code{nil}, since backup files | |
467 are redundant when you store all the previous versions in a version | |
468 control system. @xref{VC Workfile Handling}. | |
469 | |
28526
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
470 @vindex backup-enable-predicate |
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
471 @vindex temporary-file-directory |
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
472 @vindex small-temporary-file-directory |
25829 | 473 The default value of the @code{backup-enable-predicate} variable |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
474 prevents backup files being written for files in the directories used |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
475 for temporary files, specified by @code{temporary-file-directory} or |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
476 @code{small-temporary-file-directory}. |
25829 | 477 |
478 At your option, Emacs can keep either a single backup file or a series of | |
479 numbered backup files for each file that you edit. | |
480 | |
481 Emacs makes a backup for a file only the first time the file is saved | |
482 from one buffer. No matter how many times you save a file, its backup file | |
483 continues to contain the contents from before the file was visited. | |
484 Normally this means that the backup file contains the contents from before | |
485 the current editing session; however, if you kill the buffer and then visit | |
486 the file again, a new backup file will be made by the next save. | |
487 | |
488 You can also explicitly request making another backup file from a | |
489 buffer even though it has already been saved at least once. If you save | |
490 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made | |
491 into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s} | |
492 saves the buffer, but first makes the previous file contents into a new | |
493 backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a | |
494 backup from the previous contents, and arranges to make another from the | |
495 newly saved contents, if you save again. | |
496 | |
497 @menu | |
498 * Names: Backup Names. How backup files are named; | |
499 choosing single or numbered backup files. | |
500 * Deletion: Backup Deletion. Emacs deletes excess numbered backups. | |
501 * Copying: Backup Copying. Backups can be made by copying or renaming. | |
502 @end menu | |
503 | |
504 @node Backup Names | |
505 @subsubsection Single or Numbered Backups | |
506 | |
507 If you choose to have a single backup file (this is the default), | |
28526
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
508 the backup file's name is normally constructed by appending @samp{~} to the |
25829 | 509 file name being edited; thus, the backup file for @file{eval.c} would |
510 be @file{eval.c~}. | |
511 | |
28526
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
512 @vindex make-backup-file-name-function |
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
513 @vindex backup-directory-alist |
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
514 You can change this behaviour by defining the variable |
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
515 @code{make-backup-file-name-function} to a suitable function. |
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
516 Alternatively you can customize the variable |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
517 @var{backup-directory-alist} to specify that files matching certain |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
518 patterns should be backed up in specific directories. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
519 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
520 A typical use is to add an element @code{("." . @var{dir})} to make |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
521 all backups in the directory with absolute name @var{dir}; Emacs |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
522 modifies the backup file names to avoid clashes between files with the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
523 same names originating in different directories. Alternatively, |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
524 adding, say, @code{("." ".~")} would make backups in the invisible |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
525 subdirectory @file{.~} of the original file's directory. Emacs |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
526 creates the directory, if necessary, to make the backup. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
527 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
528 If access control stops Emacs from writing backup files under the usual |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
529 names, it writes the backup file as @file{%backup%~} in your home |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
530 directory. Only one such file can exist, so only the most recently |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
531 made such backup is available. |
28526
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
532 |
25829 | 533 If you choose to have a series of numbered backup files, backup file |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
534 names contain @samp{.~}, the number, and another @samp{~} after the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
535 original file name. Thus, the backup files of @file{eval.c} would be |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
536 called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
537 through names like @file{eval.c.~259~} and beyond. The variable |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
538 @code{backup-directory-alist} applies to numbered backups just as |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
539 usual. |
25829 | 540 |
541 @vindex version-control | |
542 The choice of single backup or numbered backups is controlled by the | |
543 variable @code{version-control}. Its possible values are | |
544 | |
545 @table @code | |
546 @item t | |
547 Make numbered backups. | |
548 @item nil | |
549 Make numbered backups for files that have numbered backups already. | |
550 Otherwise, make single backups. | |
551 @item never | |
552 Do not in any case make numbered backups; always make single backups. | |
553 @end table | |
554 | |
555 @noindent | |
556 You can set @code{version-control} locally in an individual buffer to | |
557 control the making of backups for that buffer's file. For example, | |
558 Rmail mode locally sets @code{version-control} to @code{never} to make sure | |
559 that there is only one backup for an Rmail file. @xref{Locals}. | |
560 | |
29107 | 561 @cindex @env{VERSION_CONTROL} environment variable |
562 If you set the environment variable @env{VERSION_CONTROL}, to tell | |
25829 | 563 various GNU utilities what to do with backup files, Emacs also obeys the |
564 environment variable by setting the Lisp variable @code{version-control} | |
565 accordingly at startup. If the environment variable's value is @samp{t} | |
566 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the | |
567 value is @samp{nil} or @samp{existing}, then @code{version-control} | |
568 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then | |
569 @code{version-control} becomes @code{never}. | |
570 | |
571 @node Backup Deletion | |
572 @subsubsection Automatic Deletion of Backups | |
573 | |
574 To prevent unlimited consumption of disk space, Emacs can delete numbered | |
575 backup versions automatically. Generally Emacs keeps the first few backups | |
576 and the latest few backups, deleting any in between. This happens every | |
577 time a new backup is made. | |
578 | |
579 @vindex kept-old-versions | |
580 @vindex kept-new-versions | |
581 The two variables @code{kept-old-versions} and | |
582 @code{kept-new-versions} control this deletion. Their values are, | |
583 respectively the number of oldest (lowest-numbered) backups to keep and | |
584 the number of newest (highest-numbered) ones to keep, each time a new | |
585 backup is made. Recall that these values are used just after a new | |
586 backup version is made; that newly made backup is included in the count | |
587 in @code{kept-new-versions}. By default, both variables are 2. | |
588 | |
589 @vindex delete-old-versions | |
590 If @code{delete-old-versions} is non-@code{nil}, the excess | |
591 middle versions are deleted without a murmur. If it is @code{nil}, the | |
592 default, then you are asked whether the excess middle versions should | |
593 really be deleted. | |
594 | |
595 Dired's @kbd{.} (Period) command can also be used to delete old versions. | |
596 @xref{Dired Deletion}. | |
597 | |
598 @node Backup Copying | |
599 @subsubsection Copying vs.@: Renaming | |
600 | |
601 Backup files can be made by copying the old file or by renaming it. This | |
602 makes a difference when the old file has multiple names. If the old file | |
603 is renamed into the backup file, then the alternate names become names for | |
604 the backup file. If the old file is copied instead, then the alternate | |
605 names remain names for the file that you are editing, and the contents | |
606 accessed by those names will be the new contents. | |
607 | |
608 The method of making a backup file may also affect the file's owner | |
609 and group. If copying is used, these do not change. If renaming is used, | |
610 you become the file's owner, and the file's group becomes the default | |
611 (different operating systems have different defaults for the group). | |
612 | |
613 Having the owner change is usually a good idea, because then the owner | |
614 always shows who last edited the file. Also, the owners of the backups | |
615 show who produced those versions. Occasionally there is a file whose | |
616 owner should not change; it is a good idea for such files to contain | |
617 local variable lists to set @code{backup-by-copying-when-mismatch} | |
618 locally (@pxref{File Variables}). | |
619 | |
620 @vindex backup-by-copying | |
621 @vindex backup-by-copying-when-linked | |
622 @vindex backup-by-copying-when-mismatch | |
31043
31a21ae1de1f
Document backup-by-copying-when-privileged-mismatch.
Eli Zaretskii <eliz@gnu.org>
parents:
29683
diff
changeset
|
623 @vindex backup-by-copying-when-privileged-mismatch |
31a21ae1de1f
Document backup-by-copying-when-privileged-mismatch.
Eli Zaretskii <eliz@gnu.org>
parents:
29683
diff
changeset
|
624 @cindex file ownership, and backup |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
625 @cindex backup, and user-id |
31043
31a21ae1de1f
Document backup-by-copying-when-privileged-mismatch.
Eli Zaretskii <eliz@gnu.org>
parents:
29683
diff
changeset
|
626 The choice of renaming or copying is controlled by four variables. |
25829 | 627 Renaming is the default choice. If the variable |
628 @code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, | |
629 if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, | |
630 then copying is used for files that have multiple names, but renaming | |
631 may still be used when the file being edited has only one name. If the | |
632 variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then | |
633 copying is used if renaming would cause the file's owner or group to | |
634 change. @code{backup-by-copying-when-mismatch} is @code{t} by default | |
31043
31a21ae1de1f
Document backup-by-copying-when-privileged-mismatch.
Eli Zaretskii <eliz@gnu.org>
parents:
29683
diff
changeset
|
635 if you start Emacs as the superuser. The fourth variable, |
31a21ae1de1f
Document backup-by-copying-when-privileged-mismatch.
Eli Zaretskii <eliz@gnu.org>
parents:
29683
diff
changeset
|
636 @code{backup-by-copying-when-privileged-mismatch}, gives the highest |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
637 numeric user-id for which @code{backup-by-copying-when-mismatch} will be |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
638 forced on. This is useful when low-numbered user-id are assigned to |
31043
31a21ae1de1f
Document backup-by-copying-when-privileged-mismatch.
Eli Zaretskii <eliz@gnu.org>
parents:
29683
diff
changeset
|
639 special system users, such as @code{root}, @code{bin}, @code{daemon}, |
31a21ae1de1f
Document backup-by-copying-when-privileged-mismatch.
Eli Zaretskii <eliz@gnu.org>
parents:
29683
diff
changeset
|
640 etc., which must maintain ownership of files. |
25829 | 641 |
642 When a file is managed with a version control system (@pxref{Version | |
643 Control}), Emacs does not normally make backups in the usual way for | |
644 that file. But check-in and check-out are similar in some ways to | |
645 making backups. One unfortunate similarity is that these operations | |
646 typically break hard links, disconnecting the file name you visited from | |
647 any alternate names for the same file. This has nothing to do with | |
648 Emacs---the version control system does it. | |
649 | |
650 @node Interlocking | |
651 @subsection Protection against Simultaneous Editing | |
652 | |
653 @cindex file dates | |
654 @cindex simultaneous editing | |
655 Simultaneous editing occurs when two users visit the same file, both | |
656 make changes, and then both save them. If nobody were informed that | |
657 this was happening, whichever user saved first would later find that his | |
658 changes were lost. | |
659 | |
660 On some systems, Emacs notices immediately when the second user starts | |
661 to change the file, and issues an immediate warning. On all systems, | |
662 Emacs checks when you save the file, and warns if you are about to | |
663 overwrite another user's changes. You can prevent loss of the other | |
664 user's work by taking the proper corrective action instead of saving the | |
665 file. | |
666 | |
667 @findex ask-user-about-lock | |
668 @cindex locking files | |
669 When you make the first modification in an Emacs buffer that is | |
670 visiting a file, Emacs records that the file is @dfn{locked} by you. | |
671 (It does this by creating a symbolic link in the same directory with a | |
672 different name.) Emacs removes the lock when you save the changes. The | |
673 idea is that the file is locked whenever an Emacs buffer visiting it has | |
674 unsaved changes. | |
675 | |
676 @cindex collision | |
677 If you begin to modify the buffer while the visited file is locked by | |
678 someone else, this constitutes a @dfn{collision}. When Emacs detects a | |
679 collision, it asks you what to do, by calling the Lisp function | |
680 @code{ask-user-about-lock}. You can redefine this function for the sake | |
681 of customization. The standard definition of this function asks you a | |
682 question and accepts three possible answers: | |
683 | |
684 @table @kbd | |
685 @item s | |
686 Steal the lock. Whoever was already changing the file loses the lock, | |
687 and you gain the lock. | |
688 @item p | |
689 Proceed. Go ahead and edit the file despite its being locked by someone else. | |
690 @item q | |
691 Quit. This causes an error (@code{file-locked}) and the modification you | |
692 were trying to make in the buffer does not actually take place. | |
693 @end table | |
694 | |
695 Note that locking works on the basis of a file name; if a file has | |
696 multiple names, Emacs does not realize that the two names are the same file | |
697 and cannot prevent two users from editing it simultaneously under different | |
698 names. However, basing locking on names means that Emacs can interlock the | |
699 editing of new files that will not really exist until they are saved. | |
700 | |
701 Some systems are not configured to allow Emacs to make locks, and | |
702 there are cases where lock files cannot be written. In these cases, | |
703 Emacs cannot detect trouble in advance, but it still can detect the | |
704 collision when you try to save a file and overwrite someone else's | |
705 changes. | |
706 | |
707 If Emacs or the operating system crashes, this may leave behind lock | |
708 files which are stale. So you may occasionally get warnings about | |
709 spurious collisions. When you determine that the collision is spurious, | |
710 just use @kbd{p} to tell Emacs to go ahead anyway. | |
711 | |
712 Every time Emacs saves a buffer, it first checks the last-modification | |
713 date of the existing file on disk to verify that it has not changed since the | |
714 file was last visited or saved. If the date does not match, it implies | |
715 that changes were made in the file in some other way, and these changes are | |
716 about to be lost if Emacs actually does save. To prevent this, Emacs | |
717 prints a warning message and asks for confirmation before saving. | |
718 Occasionally you will know why the file was changed and know that it does | |
719 not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should | |
720 cancel the save with @kbd{C-g} and investigate the situation. | |
721 | |
722 The first thing you should do when notified that simultaneous editing | |
723 has already taken place is to list the directory with @kbd{C-u C-x C-d} | |
724 (@pxref{Directories}). This shows the file's current author. You | |
725 should attempt to contact him to warn him not to continue editing. | |
726 Often the next step is to save the contents of your Emacs buffer under a | |
727 different name, and use @code{diff} to compare the two files.@refill | |
728 | |
31076 | 729 @node File Shadowing |
730 @subsection Shadowing Files | |
731 @cindex shadow files | |
732 @cindex file shadows | |
733 | |
734 @table @kbd | |
735 @item M-x shadow-initialize | |
736 Set up file shadowing. | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
737 @item M-x shadow-define-literal-group |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
738 Declare a single file to be shared between sites. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
739 @item M-x shadow-define-regexp-group |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
740 Make all files that match each of a group of files be shared between hosts. |
31076 | 741 @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} |
742 Define a shadow file cluster @var{name}. | |
743 @item M-x shadow-copy-files | |
744 Copy all pending shadow files. | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
745 @item M-x shadow-cancel |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
746 Cancel the instruction to shadow some files. |
31076 | 747 @end table |
748 | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
749 You can arrange to keep identical @dfn{shadow} copies of certain files |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
750 in more than one place---possibly on different machines. To do this, |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
751 first you must set up a @dfn{shadow file group}, which is a set of |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
752 identically-named files shared between a list of sites. The file |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
753 group is permanent and applies to further Emacs sessions as well as |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
754 the current one. Once the group is set up, every time you exit Emacs, |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
755 it will copy the file you edited to the other files in its group. You |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
756 can also do the copying without exiting Emacs, by typing @kbd{M-x |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
757 shadow-copy-files}. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
758 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
759 To set up a file group, use @kbd{M-x shadow-define-literal-group} or |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
760 @kbd{M-x shadow-define-regexp-group}. See their documentation strings |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
761 for further information. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
762 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
763 Before copying a file to its shadows, Emacs asks for confirmation. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
764 You can answer ``no'' to bypass copying of this file, this time. If |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
765 you want to cancel the shadowing permanently for a certain file, use |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
766 @kbd{M-x shadow-cancel} to eliminate or change the shadow file group. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
767 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
768 A @dfn{shadow cluster} is a group of hosts that share directories, so |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
769 that copying to or from one of them is sufficient to update the file |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
770 on all of them. Each shadow cluster has a name, and specifies the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
771 network address of a primary host (the one we copy files to), and a |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
772 regular expression that matches the hostnames of all the other hosts |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
773 in the cluster. You can define a shadow cluster with @kbd{M-x |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
774 shadow-define-cluster}. |
31076 | 775 |
35524 | 776 @node Time Stamps |
777 @subsection Updating Time Stamps Automatically | |
778 @findex time-stamp | |
779 @cindex time stamps | |
780 @cindex modification dates | |
35620 | 781 @cindex locale, date format |
35524 | 782 |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
783 You can arrange put a time stamp in a file, so that it will be updated |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
784 automatically each time you edit and save the file. The time stamp |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
785 has to be in the first eight lines of the file, and you should |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
786 insert it like this: |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
787 |
35524 | 788 @example |
789 Time-stamp: <> | |
790 @end example | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
791 |
35524 | 792 @noindent |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
793 or like this: |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
794 |
35524 | 795 @example |
796 Time-stamp: "" | |
797 @end example | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
798 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
799 Then add the hook function @code{time-stamp} to the hook |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
800 @code{write-file-hooks}; that hook function will automatically update |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
801 the time stamp, inserting the current date and time when you save the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
802 file. You can also use the command @kbd{M-x time-stamp} to update the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
803 time stamp manually. For other customizations, see the Custom group |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
804 @code{time-stamp}. Note that non-numeric fields in the time stamp are |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
805 formatted according to your locale setting (@pxref{Environment}). |
35524 | 806 |
25829 | 807 @node Reverting |
808 @section Reverting a Buffer | |
809 @findex revert-buffer | |
810 @cindex drastic changes | |
811 | |
812 If you have made extensive changes to a file and then change your mind | |
813 about them, you can get rid of them by reading in the previous version | |
814 of the file. To do this, use @kbd{M-x revert-buffer}, which operates on | |
815 the current buffer. Since reverting a buffer unintentionally could lose | |
816 a lot of work, you must confirm this command with @kbd{yes}. | |
817 | |
818 @code{revert-buffer} keeps point at the same distance (measured in | |
819 characters) from the beginning of the file. If the file was edited only | |
820 slightly, you will be at approximately the same piece of text after | |
821 reverting as before. If you have made drastic changes, the same value of | |
822 point in the old file may address a totally different piece of text. | |
823 | |
824 Reverting marks the buffer as ``not modified'' until another change is | |
825 made. | |
826 | |
827 Some kinds of buffers whose contents reflect data bases other than files, | |
828 such as Dired buffers, can also be reverted. For them, reverting means | |
829 recalculating their contents from the appropriate data base. Buffers | |
830 created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer} | |
831 reports an error when asked to do so. | |
832 | |
833 @vindex revert-without-query | |
834 When you edit a file that changes automatically and frequently---for | |
835 example, a log of output from a process that continues to run---it may be | |
836 useful for Emacs to revert the file without querying you, whenever you | |
837 visit the file again with @kbd{C-x C-f}. | |
838 | |
839 To request this behavior, set the variable @code{revert-without-query} | |
840 to a list of regular expressions. When a file name matches one of these | |
841 regular expressions, @code{find-file} and @code{revert-buffer} will | |
842 revert it automatically if it has changed---provided the buffer itself | |
843 is not modified. (If you have edited the text, it would be wrong to | |
844 discard your changes.) | |
845 | |
846 @node Auto Save | |
847 @section Auto-Saving: Protection Against Disasters | |
848 @cindex Auto Save mode | |
849 @cindex mode, Auto Save | |
850 @cindex crashes | |
851 | |
852 Emacs saves all the visited files from time to time (based on counting | |
853 your keystrokes) without being asked. This is called @dfn{auto-saving}. | |
854 It prevents you from losing more than a limited amount of work if the | |
855 system crashes. | |
856 | |
857 When Emacs determines that it is time for auto-saving, each buffer is | |
858 considered, and is auto-saved if auto-saving is turned on for it and it | |
859 has been changed since the last time it was auto-saved. The message | |
860 @samp{Auto-saving...} is displayed in the echo area during auto-saving, | |
861 if any files are actually auto-saved. Errors occurring during | |
862 auto-saving are caught so that they do not interfere with the execution | |
863 of commands you have been typing. | |
864 | |
865 @menu | |
866 * Files: Auto Save Files. The file where auto-saved changes are | |
867 actually made until you save the file. | |
868 * Control: Auto Save Control. Controlling when and how often to auto-save. | |
869 * Recover:: Recovering text from auto-save files. | |
870 @end menu | |
871 | |
872 @node Auto Save Files | |
873 @subsection Auto-Save Files | |
874 | |
875 Auto-saving does not normally save in the files that you visited, because | |
876 it can be very undesirable to save a program that is in an inconsistent | |
877 state when you have made half of a planned change. Instead, auto-saving | |
878 is done in a different file called the @dfn{auto-save file}, and the | |
879 visited file is changed only when you request saving explicitly (such as | |
880 with @kbd{C-x C-s}). | |
881 | |
882 Normally, the auto-save file name is made by appending @samp{#} to the | |
883 front and rear of the visited file name. Thus, a buffer visiting file | |
884 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that | |
885 are not visiting files are auto-saved only if you request it explicitly; | |
886 when they are auto-saved, the auto-save file name is made by appending | |
887 @samp{#%} to the front and @samp{#} to the rear of buffer name. For | |
888 example, the @samp{*mail*} buffer in which you compose messages to be | |
889 sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file | |
890 names are made this way unless you reprogram parts of Emacs to do | |
891 something different (the functions @code{make-auto-save-file-name} and | |
892 @code{auto-save-file-name-p}). The file name to be used for auto-saving | |
893 in a buffer is calculated when auto-saving is turned on in that buffer. | |
894 | |
895 When you delete a substantial part of the text in a large buffer, auto | |
896 save turns off temporarily in that buffer. This is because if you | |
897 deleted the text unintentionally, you might find the auto-save file more | |
898 useful if it contains the deleted text. To reenable auto-saving after | |
899 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x | |
900 auto-save}. | |
901 | |
902 @vindex auto-save-visited-file-name | |
903 If you want auto-saving to be done in the visited file, set the variable | |
904 @code{auto-save-visited-file-name} to be non-@code{nil}. In this mode, | |
905 there is really no difference between auto-saving and explicit saving. | |
906 | |
907 @vindex delete-auto-save-files | |
908 A buffer's auto-save file is deleted when you save the buffer in its | |
909 visited file. To inhibit this, set the variable @code{delete-auto-save-files} | |
910 to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or | |
911 @code{set-visited-file-name} renames any auto-save file to go with | |
912 the new visited name. | |
913 | |
914 @node Auto Save Control | |
915 @subsection Controlling Auto-Saving | |
916 | |
917 @vindex auto-save-default | |
918 @findex auto-save-mode | |
919 Each time you visit a file, auto-saving is turned on for that file's | |
920 buffer if the variable @code{auto-save-default} is non-@code{nil} (but not | |
921 in batch mode; @pxref{Entering Emacs}). The default for this variable is | |
922 @code{t}, so auto-saving is the usual practice for file-visiting buffers. | |
923 Auto-saving can be turned on or off for any existing buffer with the | |
924 command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x | |
925 auto-save-mode} turns auto-saving on with a positive argument, off with a | |
926 zero or negative argument; with no argument, it toggles. | |
927 | |
928 @vindex auto-save-interval | |
929 Emacs does auto-saving periodically based on counting how many characters | |
930 you have typed since the last time auto-saving was done. The variable | |
931 @code{auto-save-interval} specifies how many characters there are between | |
932 auto-saves. By default, it is 300. | |
933 | |
934 @vindex auto-save-timeout | |
935 Auto-saving also takes place when you stop typing for a while. The | |
936 variable @code{auto-save-timeout} says how many seconds Emacs should | |
937 wait before it does an auto save (and perhaps also a garbage | |
938 collection). (The actual time period is longer if the current buffer is | |
939 long; this is a heuristic which aims to keep out of your way when you | |
940 are editing long buffers, in which auto-save takes an appreciable amount | |
941 of time.) Auto-saving during idle periods accomplishes two things: | |
942 first, it makes sure all your work is saved if you go away from the | |
943 terminal for a while; second, it may avoid some auto-saving while you | |
944 are actually typing. | |
945 | |
946 Emacs also does auto-saving whenever it gets a fatal error. This | |
947 includes killing the Emacs job with a shell command such as @samp{kill | |
948 %emacs}, or disconnecting a phone line or network connection. | |
949 | |
950 @findex do-auto-save | |
951 You can request an auto-save explicitly with the command @kbd{M-x | |
952 do-auto-save}. | |
953 | |
954 @node Recover | |
955 @subsection Recovering Data from Auto-Saves | |
956 | |
957 @findex recover-file | |
958 You can use the contents of an auto-save file to recover from a loss | |
959 of data with the command @kbd{M-x recover-file @key{RET} @var{file} | |
960 @key{RET}}. This visits @var{file} and then (after your confirmation) | |
961 restores the contents from its auto-save file @file{#@var{file}#}. | |
962 You can then save with @kbd{C-x C-s} to put the recovered text into | |
963 @var{file} itself. For example, to recover file @file{foo.c} from its | |
964 auto-save file @file{#foo.c#}, do:@refill | |
965 | |
966 @example | |
967 M-x recover-file @key{RET} foo.c @key{RET} | |
968 yes @key{RET} | |
969 C-x C-s | |
970 @end example | |
971 | |
972 Before asking for confirmation, @kbd{M-x recover-file} displays a | |
973 directory listing describing the specified file and the auto-save file, | |
974 so you can compare their sizes and dates. If the auto-save file | |
975 is older, @kbd{M-x recover-file} does not offer to read it. | |
976 | |
977 @findex recover-session | |
978 If Emacs or the computer crashes, you can recover all the files you | |
979 were editing from their auto save files with the command @kbd{M-x | |
980 recover-session}. This first shows you a list of recorded interrupted | |
981 sessions. Move point to the one you choose, and type @kbd{C-c C-c}. | |
982 | |
983 Then @code{recover-session} asks about each of the files that were | |
984 being edited during that session, asking whether to recover that file. | |
985 If you answer @kbd{y}, it calls @code{recover-file}, which works in its | |
986 normal fashion. It shows the dates of the original file and its | |
987 auto-save file, and asks once again whether to recover that file. | |
988 | |
989 When @code{recover-session} is done, the files you've chosen to | |
990 recover are present in Emacs buffers. You should then save them. Only | |
991 this---saving them---updates the files themselves. | |
992 | |
993 @vindex auto-save-list-file-prefix | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
994 Emacs records interrupted sessions for later recovery in files named |
31076 | 995 @file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. The |
35337 | 996 @samp{~/.emacs.d/auto-save-list/.saves-} portion of these names comes |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
997 from the value of @code{auto-save-list-file-prefix}. You can record |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
998 sessions in a different place by customizing that variable. If you |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
999 set @code{auto-save-list-file-prefix} to @code{nil} in your |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1000 @file{.emacs} file, sessions are not recorded for recovery. |
25829 | 1001 |
1002 @node File Aliases | |
1003 @section File Name Aliases | |
1004 | |
1005 Symbolic links and hard links both make it possible for several file | |
1006 names to refer to the same file. Hard links are alternate names that | |
1007 refer directly to the file; all the names are equally valid, and no one | |
1008 of them is preferred. By contrast, a symbolic link is a kind of defined | |
1009 alias: when @file{foo} is a symbolic link to @file{bar}, you can use | |
1010 either name to refer to the file, but @file{bar} is the real name, while | |
1011 @file{foo} is just an alias. More complex cases occur when symbolic | |
1012 links point to directories. | |
1013 | |
1014 If you visit two names for the same file, normally Emacs makes | |
1015 two different buffers, but it warns you about the situation. | |
1016 | |
33278
7b666d4d4007
(File Aliases): Change description of find-file-existing-other-name
Gerd Moellmann <gerd@gnu.org>
parents:
32221
diff
changeset
|
1017 @vindex find-file-existing-other-name |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1018 Normally, if you visit a file which Emacs is already visiting under |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1019 a different name, Emacs displays a message in the echo area and uses |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1020 the existing buffer visiting that file. This can happen on systems |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1021 that support symbolic links, or if you use a long file name on a |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1022 system that truncates long file names. You can disable this feature |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1023 by setting the variable @code{find-file-existing-other-name} to |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1024 @code{nil}. Then if you visit the same file under two different names, |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1025 you get a separate buffer for each file name. |
25829 | 1026 |
1027 @vindex find-file-visit-truename | |
1028 @cindex truenames of files | |
1029 @cindex file truenames | |
1030 If the variable @code{find-file-visit-truename} is non-@code{nil}, | |
1031 then the file name recorded for a buffer is the file's @dfn{truename} | |
1032 (made by replacing all symbolic links with their target names), rather | |
1033 than the name you specify. Setting @code{find-file-visit-truename} also | |
1034 implies the effect of @code{find-file-existing-other-name}. | |
1035 | |
1036 @node Version Control | |
1037 @section Version Control | |
1038 @cindex version control | |
1039 | |
1040 @dfn{Version control systems} are packages that can record multiple | |
1041 versions of a source file, usually storing the unchanged parts of the | |
1042 file just once. Version control systems also record history information | |
1043 such as the creation time of each version, who created it, and a | |
1044 description of what was changed in that version. | |
1045 | |
1046 The Emacs version control interface is called VC. Its commands work | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1047 with three version control systems---RCS, CVS and SCCS. The GNU |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1048 project recommends RCS and CVS, which are free software and available |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1049 from the Free Software Foundation. We also have free software to |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1050 replace SCCS, known as CSSC; if you are using SCCS and don't want to |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1051 make the incompatible change to RCS or CVS, you can switch to CSSC. |
25829 | 1052 |
1053 @menu | |
1054 * Introduction to VC:: How version control works in general. | |
1055 * VC Mode Line:: How the mode line shows version control status. | |
1056 * Basic VC Editing:: How to edit a file under version control. | |
1057 * Old Versions:: Examining and comparing old versions. | |
1058 * Secondary VC Commands:: The commands used a little less frequently. | |
1059 * Branches:: Multiple lines of development. | |
1060 * Snapshots:: Sets of file versions treated as a unit. | |
1061 * Miscellaneous VC:: Various other commands and features of VC. | |
1062 * Customizing VC:: Variables that change VC's behavior. | |
1063 @end menu | |
1064 | |
1065 @node Introduction to VC | |
1066 @subsection Introduction to Version Control | |
1067 | |
1068 VC allows you to use a version control system from within Emacs, | |
1069 integrating the version control operations smoothly with editing. VC | |
1070 provides a uniform interface to version control, so that regardless of | |
1071 which version control system is in use, you can use it the same way. | |
1072 | |
1073 This section provides a general overview of version control, and | |
1074 describes the version control systems that VC supports. You can skip | |
1075 this section if you are already familiar with the version control system | |
1076 you want to use. | |
1077 | |
1078 @menu | |
1079 * Version Systems:: Supported version control back-end systems. | |
1080 * VC Concepts:: Words and concepts related to version control. | |
1081 @end menu | |
1082 | |
1083 @node Version Systems | |
1084 @subsubsection Supported Version Control Systems | |
1085 | |
1086 @cindex RCS | |
1087 @cindex back end (version control) | |
1088 VC currently works with three different version control systems or | |
1089 ``back ends'': RCS, CVS, and SCCS. | |
1090 | |
1091 RCS is a free version control system that is available from the Free | |
1092 Software Foundation. It is perhaps the most mature of the supported | |
1093 back ends, and the VC commands are conceptually closest to RCS. Almost | |
1094 everything you can do with RCS can be done through VC. | |
1095 | |
1096 @cindex CVS | |
1097 CVS is built on top of RCS, and extends the features of RCS, allowing | |
1098 for more sophisticated release management, and concurrent multi-user | |
1099 development. VC supports basic editing operations under CVS, but for | |
1100 some less common tasks you still need to call CVS from the command line. | |
1101 Note also that before using CVS you must set up a repository, which is a | |
1102 subject too complex to treat here. | |
1103 | |
1104 @cindex SCCS | |
1105 SCCS is a proprietary but widely used version control system. In | |
1106 terms of capabilities, it is the weakest of the three that VC | |
1107 supports. VC compensates for certain features missing in SCCS | |
1108 (snapshots, for example) by implementing them itself, but some other VC | |
1109 features, such as multiple branches, are not available with SCCS. You | |
1110 should use SCCS only if for some reason you cannot use RCS. | |
1111 | |
1112 @node VC Concepts | |
1113 @subsubsection Concepts of Version Control | |
1114 | |
1115 @cindex master file | |
1116 @cindex registered file | |
1117 When a file is under version control, we also say that it is | |
1118 @dfn{registered} in the version control system. Each registered file | |
1119 has a corresponding @dfn{master file} which represents the file's | |
1120 present state plus its change history---enough to reconstruct the | |
1121 current version or any earlier version. Usually the master file also | |
1122 records a @dfn{log entry} for each version, describing in words what was | |
1123 changed in that version. | |
1124 | |
1125 @cindex work file | |
1126 @cindex checking out files | |
1127 The file that is maintained under version control is sometimes called | |
1128 the @dfn{work file} corresponding to its master file. You edit the work | |
1129 file and make changes in it, as you would with an ordinary file. (With | |
1130 SCCS and RCS, you must @dfn{lock} the file before you start to edit it.) | |
1131 After you are done with a set of changes, you @dfn{check the file in}, | |
1132 which records the changes in the master file, along with a log entry for | |
1133 them. | |
1134 | |
1135 With CVS, there are usually multiple work files corresponding to a | |
1136 single master file---often each user has his own copy. It is also | |
1137 possible to use RCS in this way, but this is not the usual way to use | |
1138 RCS. | |
1139 | |
1140 @cindex locking and version control | |
1141 A version control system typically has some mechanism to coordinate | |
1142 between users who want to change the same file. One method is | |
1143 @dfn{locking} (analogous to the locking that Emacs uses to detect | |
1144 simultaneous editing of a file, but distinct from it). The other method | |
1145 is to merge your changes with other people's changes when you check them | |
1146 in. | |
1147 | |
1148 With version control locking, work files are normally read-only so | |
1149 that you cannot change them. You ask the version control system to make | |
1150 a work file writable for you by locking it; only one user can do | |
1151 this at any given time. When you check in your changes, that unlocks | |
1152 the file, making the work file read-only again. This allows other users | |
1153 to lock the file to make further changes. SCCS always uses locking, and | |
1154 RCS normally does. | |
1155 | |
1156 The other alternative for RCS is to let each user modify the work file | |
1157 at any time. In this mode, locking is not required, but it is | |
1158 permitted; check-in is still the way to record a new version. | |
1159 | |
1160 CVS normally allows each user to modify his own copy of the work file | |
1161 at any time, but requires merging with changes from other users at | |
1162 check-in time. However, CVS can also be set up to require locking. | |
1163 (@pxref{Backend Options}). | |
1164 | |
1165 @node VC Mode Line | |
1166 @subsection Version Control and the Mode Line | |
1167 | |
1168 When you visit a file that is under version control, Emacs indicates | |
1169 this on the mode line. For example, @samp{RCS-1.3} says that RCS is | |
1170 used for that file, and the current version is 1.3. | |
1171 | |
1172 The character between the back-end name and the version number | |
1173 indicates the version control status of the file. @samp{-} means that | |
1174 the work file is not locked (if locking is in use), or not modified (if | |
1175 locking is not in use). @samp{:} indicates that the file is locked, or | |
1176 that it is modified. If the file is locked by some other user (for | |
1177 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. | |
1178 | |
1179 @node Basic VC Editing | |
1180 @subsection Basic Editing under Version Control | |
1181 | |
1182 The principal VC command is an all-purpose command that performs | |
1183 either locking or check-in, depending on the situation. | |
1184 | |
1185 @table @kbd | |
1186 @item C-x C-q | |
1187 @itemx C-x v v | |
1188 Perform the next logical version control operation on this file. | |
1189 @end table | |
1190 | |
1191 @findex vc-next-action | |
1192 @findex vc-toggle-read-only | |
1193 @kindex C-x v v | |
1194 @kindex C-x C-q @r{(Version Control)} | |
1195 Strictly speaking, the command for this job is @code{vc-next-action}, | |
1196 bound to @kbd{C-x v v}. However, the normal meaning of @kbd{C-x C-q} is | |
1197 to make a read-only buffer writable, or vice versa; we have extended it | |
1198 to do the same job properly for files managed by version control, by | |
1199 performing the appropriate version control operations. When you type | |
1200 @kbd{C-x C-q} on a registered file, it acts like @kbd{C-x v v}. | |
1201 | |
1202 The precise action of this command depends on the state of the file, | |
1203 and whether the version control system uses locking or not. SCCS and | |
1204 RCS normally use locking; CVS normally does not use locking. | |
1205 | |
1206 @menu | |
1207 * VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. | |
1208 * Without Locking:: Without locking: default mode for CVS. | |
1209 * Log Buffer:: Features available in log entry buffers. | |
1210 @end menu | |
1211 | |
1212 @node VC with Locking | |
1213 @subsubsection Basic Version Control with Locking | |
1214 | |
1215 If locking is used for the file (as with SCCS, and RCS in its default | |
1216 mode), @kbd{C-x C-q} can either lock a file or check it in: | |
1217 | |
1218 @itemize @bullet | |
1219 @item | |
1220 If the file is not locked, @kbd{C-x C-q} locks it, and | |
1221 makes it writable so that you can change it. | |
1222 | |
1223 @item | |
1224 If the file is locked by you, and contains changes, @kbd{C-x C-q} checks | |
1225 in the changes. In order to do this, it first reads the log entry | |
1226 for the new version. @xref{Log Buffer}. | |
1227 | |
1228 @item | |
1229 If the file is locked by you, but you have not changed it since you | |
1230 locked it, @kbd{C-x C-q} releases the lock and makes the file read-only | |
1231 again. | |
1232 | |
1233 @item | |
1234 If the file is locked by some other user, @kbd{C-x C-q} asks you whether | |
1235 you want to ``steal the lock'' from that user. If you say yes, the file | |
1236 becomes locked by you, but a message is sent to the person who had | |
1237 formerly locked the file, to inform him of what has happened. | |
1238 @end itemize | |
1239 | |
1240 These rules also apply when you use CVS in locking mode, except | |
1241 that there is no such thing as stealing a lock. | |
1242 | |
1243 @node Without Locking | |
1244 @subsubsection Basic Version Control without Locking | |
1245 | |
1246 When there is no locking---the default for CVS---work files are always | |
1247 writable; you do not need to do anything before you begin to edit a | |
1248 file. The status indicator on the mode line is @samp{-} if the file is | |
1249 unmodified; it flips to @samp{:} as soon as you save any changes in the | |
1250 work file. | |
1251 | |
1252 Here is what @kbd{C-x C-q} does when using CVS: | |
1253 | |
1254 @itemize @bullet | |
1255 @item | |
1256 If some other user has checked in changes into the master file, | |
1257 Emacs asks you whether you want to merge those changes into your own | |
1258 work file (@pxref{Merging}). You must do this before you can check in | |
1259 your own changes. | |
1260 | |
1261 @item | |
1262 If there are no new changes in the master file, but you have made | |
1263 modifications in your work file, @kbd{C-x C-q} checks in your changes. | |
1264 In order to do this, it first reads the log entry for the new version. | |
1265 @xref{Log Buffer}. | |
1266 | |
1267 @item | |
1268 If the file is not modified, the @kbd{C-x C-q} does nothing. | |
1269 @end itemize | |
1270 | |
1271 These rules also apply when you use RCS in the mode that does not | |
1272 require locking, except that automatic merging of changes from the | |
1273 master file is not implemented. Unfortunately, this means that nothing | |
1274 informs you if another user has checked in changes in the same file | |
1275 since you began editing it, and when this happens, his changes will be | |
1276 effectively removed when you check in your version (though they will | |
1277 remain in the master file, so they will not be entirely lost). You must | |
1278 therefore verify the current version is unchanged, before you check in your | |
1279 changes. We hope to eliminate this risk and provide automatic merging | |
1280 with RCS in a future Emacs version. | |
1281 | |
1282 In addition, locking is possible with RCS even in this mode, although | |
1283 it is not required; @kbd{C-x C-q} with an unmodified file locks the | |
1284 file, just as it does with RCS in its normal (locking) mode. | |
1285 | |
1286 @node Log Buffer | |
1287 @subsubsection Features of the Log Entry Buffer | |
1288 | |
1289 When you check in changes, @kbd{C-x C-q} first reads a log entry. It | |
1290 pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. | |
1291 When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer. | |
1292 That is when check-in really happens. | |
1293 | |
1294 To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that | |
1295 buffer. You can switch buffers and do other editing. As long as you | |
1296 don't try to check in another file, the entry you were editing remains | |
1297 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any | |
1298 time to complete the check-in. | |
1299 | |
1300 If you change several source files for the same reason, it is often | |
1301 convenient to specify the same log entry for many of the files. To do | |
1302 this, use the history of previous log entries. The commands @kbd{M-n}, | |
1303 @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the | |
1304 minibuffer history commands (except that these versions are used outside | |
1305 the minibuffer). | |
1306 | |
1307 @vindex vc-log-mode-hook | |
1308 Each time you check in a file, the log entry buffer is put into VC Log | |
1309 mode, which involves running two hooks: @code{text-mode-hook} and | |
1310 @code{vc-log-mode-hook}. @xref{Hooks}. | |
1311 | |
1312 @node Old Versions | |
1313 @subsection Examining And Comparing Old Versions | |
1314 | |
1315 One of the convenient features of version control is the ability | |
1316 to examine any version of a file, or compare two versions. | |
1317 | |
1318 @table @kbd | |
1319 @item C-x v ~ @var{version} @key{RET} | |
1320 Examine version @var{version} of the visited file, in a buffer of its | |
1321 own. | |
1322 | |
1323 @item C-x v = | |
1324 Compare the current buffer contents with the latest checked-in version | |
1325 of the file. | |
1326 | |
1327 @item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} | |
1328 Compare the specified two versions of @var{file}. | |
1329 | |
1330 @item C-x v g | |
1331 Display the result of the CVS annotate command using colors. | |
1332 @end table | |
1333 | |
1334 @findex vc-version-other-window | |
1335 @kindex C-x v ~ | |
1336 To examine an old version in toto, visit the file and then type | |
1337 @kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}). | |
1338 This puts the text of version @var{version} in a file named | |
1339 @file{@var{filename}.~@var{version}~}, and visits it in its own buffer | |
1340 in a separate window. (In RCS, you can also select an old version | |
1341 and create a branch from it. @xref{Branches}.) | |
1342 | |
1343 @findex vc-diff | |
1344 @kindex C-x v = | |
1345 But usually it is more convenient to compare two versions of the file, | |
1346 with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =} | |
1347 compares the current buffer contents (saving them in the file if | |
1348 necessary) with the last checked-in version of the file. @kbd{C-u C-x v | |
1349 =}, with a numeric argument, reads a file name and two version numbers, | |
1350 then compares those versions of the specified file. | |
1351 | |
1352 If you supply a directory name instead of the name of a registered | |
1353 file, this command compares the two specified versions of all registered | |
1354 files in that directory and its subdirectories. | |
1355 | |
1356 You can specify a checked-in version by its number; an empty input | |
1357 specifies the current contents of the work file (which may be different | |
1358 from all the checked-in versions). You can also specify a snapshot name | |
1359 (@pxref{Snapshots}) instead of one or both version numbers. | |
1360 | |
1361 This command works by running the @code{diff} utility, getting the | |
1362 options from the variable @code{diff-switches}. It displays the output | |
1363 in a special buffer in another window. Unlike the @kbd{M-x diff} | |
1364 command, @kbd{C-x v =} does not try to locate the changes in the old and | |
1365 new versions. This is because normally one or both versions do not | |
1366 exist as files when you compare them; they exist only in the records of | |
1367 the master file. @xref{Comparing Files}, for more information about | |
1368 @kbd{M-x diff}. | |
1369 | |
1370 @findex vc-annotate | |
1371 @kindex C-x v g | |
1372 For CVS-controlled files, you can display the result of the CVS | |
1373 annotate command, using colors to enhance the visual appearance. Use | |
1374 the command @kbd{M-x vc-annotate} to do this. Red means new, blue means | |
1375 old, and intermediate colors indicate intermediate ages. A prefix | |
1376 argument @var{n} specifies a stretch factor for the time scale; it makes | |
1377 each color cover a period @var{n} times as long. | |
1378 | |
1379 @node Secondary VC Commands | |
1380 @subsection The Secondary Commands of VC | |
1381 | |
1382 This section explains the secondary commands of VC; those that you might | |
1383 use once a day. | |
1384 | |
1385 @menu | |
1386 * Registering:: Putting a file under version control. | |
1387 * VC Status:: Viewing the VC status of files. | |
1388 * VC Undo:: Cancelling changes before or after check-in. | |
1389 * VC Dired Mode:: Listing files managed by version control. | |
1390 * VC Dired Commands:: Commands to use in a VC Dired buffer. | |
1391 @end menu | |
1392 | |
1393 @node Registering | |
1394 @subsubsection Registering a File for Version Control | |
1395 | |
1396 @kindex C-x v i | |
1397 @findex vc-register | |
1398 You can put any file under version control by simply visiting it, and | |
1399 then typing @w{@kbd{C-x v i}} (@code{vc-register}). | |
1400 | |
1401 @table @kbd | |
1402 @item C-x v i | |
1403 Register the visited file for version control. | |
1404 @end table | |
1405 | |
1406 @vindex vc-default-back-end | |
1407 To register the file, Emacs must choose which version control system | |
1408 to use for it. You can specify your choice explicitly by setting | |
1409 @code{vc-default-back-end} to @code{RCS}, @code{CVS} or @code{SCCS}. | |
1410 Otherwise, if there is a subdirectory named @file{RCS}, @file{SCCS}, or | |
1411 @file{CVS}, Emacs uses the corresponding version control system. In the | |
1412 absence of any specification, the default choice is RCS if RCS is | |
1413 installed, otherwise SCCS. | |
1414 | |
1415 If locking is in use, @kbd{C-x v i} leaves the file unlocked and | |
1416 read-only. Type @kbd{C-x C-q} if you wish to start editing it. After | |
1417 registering a file with CVS, you must subsequently commit the initial | |
1418 version by typing @kbd{C-x C-q}. | |
1419 | |
1420 @vindex vc-default-init-version | |
1421 The initial version number for a newly registered file is 1.1, by | |
1422 default. You can specify a different default by setting the variable | |
1423 @code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric | |
1424 argument; then it reads the initial version number for this particular | |
1425 file using the minibuffer. | |
1426 | |
1427 @vindex vc-initial-comment | |
1428 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an | |
1429 initial comment to describe the purpose of this source file. Reading | |
1430 the initial comment works like reading a log entry (@pxref{Log Buffer}). | |
1431 | |
1432 @node VC Status | |
1433 @subsubsection VC Status Commands | |
1434 | |
1435 @table @kbd | |
1436 @item C-x v l | |
1437 Display version control state and change history. | |
1438 @end table | |
1439 | |
1440 @kindex C-x v l | |
1441 @findex vc-print-log | |
1442 To view the detailed version control status and history of a file, | |
1443 type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of | |
1444 changes to the current file, including the text of the log entries. The | |
1445 output appears in a separate window. | |
1446 | |
1447 @node VC Undo | |
1448 @subsubsection Undoing Version Control Actions | |
1449 | |
1450 @table @kbd | |
1451 @item C-x v u | |
1452 Revert the buffer and the file to the last checked-in version. | |
1453 | |
1454 @item C-x v c | |
1455 Remove the last-entered change from the master for the visited file. | |
1456 This undoes your last check-in. | |
1457 @end table | |
1458 | |
1459 @kindex C-x v u | |
1460 @findex vc-revert-buffer | |
1461 If you want to discard your current set of changes and revert to the | |
1462 last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}). | |
1463 This leaves the file unlocked; if locking is in use, you must first lock | |
1464 the file again before you change it again. @kbd{C-x v u} requires | |
1465 confirmation, unless it sees that you haven't made any changes since the | |
1466 last checked-in version. | |
1467 | |
1468 @kbd{C-x v u} is also the command to unlock a file if you lock it and | |
1469 then decide not to change it. | |
1470 | |
1471 @kindex C-x v c | |
1472 @findex vc-cancel-version | |
1473 To cancel a change that you already checked in, use @kbd{C-x v c} | |
1474 (@code{vc-cancel-version}). This command discards all record of the | |
1475 most recent checked-in version. @kbd{C-x v c} also offers to revert | |
1476 your work file and buffer to the previous version (the one that precedes | |
1477 the version that is deleted). | |
1478 | |
1479 If you answer @kbd{no}, VC keeps your changes in the buffer, and locks | |
1480 the file. The no-revert option is useful when you have checked in a | |
1481 change and then discover a trivial error in it; you can cancel the | |
1482 erroneous check-in, fix the error, and check the file in again. | |
1483 | |
1484 When @kbd{C-x v c} does not revert the buffer, it unexpands all | |
1485 version control headers in the buffer instead (@pxref{Version Headers}). | |
1486 This is because the buffer no longer corresponds to any existing | |
1487 version. If you check it in again, the check-in process will expand the | |
1488 headers properly for the new version number. | |
1489 | |
1490 However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header | |
1491 automatically. If you use that header feature, you have to unexpand it | |
1492 by hand---by deleting the entry for the version that you just canceled. | |
1493 | |
1494 Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of | |
1495 work with it. To help you be careful, this command always requires | |
1496 confirmation with @kbd{yes}. Note also that this command is disabled | |
1497 under CVS, because canceling versions is very dangerous and discouraged | |
1498 with CVS. | |
1499 | |
1500 @node VC Dired Mode | |
1501 @subsubsection Dired under VC | |
1502 | |
31076 | 1503 @cindex PCL-CVS |
1504 @pindex cvs | |
1505 @cindex CVS Dired Mode | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1506 The VC Dired Mode described here works with all the version control |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1507 systems that VC supports. Another more powerful facility, designed |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1508 specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS, |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
1509 pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. |
31076 | 1510 |
25829 | 1511 @kindex C-x v d |
1512 @findex vc-directory | |
1513 When you are working on a large program, it is often useful to find | |
1514 out which files have changed within an entire directory tree, or to view | |
1515 the status of all files under version control at once, and to perform | |
1516 version control operations on collections of files. You can use the | |
1517 command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing | |
1518 that includes only files relevant for version control. | |
1519 | |
1520 @vindex vc-dired-terse-display | |
1521 @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks | |
1522 much like an ordinary Dired buffer (@pxref{Dired}); however, normally it | |
1523 shows only the noteworthy files (those locked or not up-to-date). This | |
1524 is called @dfn{terse display}. If you set the variable | |
1525 @code{vc-dired-terse-display} to @code{nil}, then VC Dired shows all | |
1526 relevant files---those managed under version control, plus all | |
1527 subdirectories (@dfn{full display}). The command @kbd{v t} in a VC | |
1528 Dired buffer toggles between terse display and full display (@pxref{VC | |
1529 Dired Commands}). | |
1530 | |
1531 @vindex vc-dired-recurse | |
1532 By default, VC Dired produces a recursive listing of noteworthy or | |
1533 relevant files at or below the given directory. You can change this by | |
1534 setting the variable @code{vc-dired-recurse} to @code{nil}; then VC | |
1535 Dired shows only the files in the given directory. | |
1536 | |
1537 The line for an individual file shows the version control state in the | |
1538 place of the hard link count, owner, group, and size of the file. If | |
1539 the file is unmodified, in sync with the master file, the version | |
1540 control state shown is blank. Otherwise it consists of text in | |
1541 parentheses. Under RCS and SCCS, the name of the user locking the file | |
1542 is shown; under CVS, an abbreviated version of the @samp{cvs status} | |
1543 output is used. Here is an example using RCS: | |
1544 | |
1545 @smallexample | |
1546 @group | |
1547 /home/jim/project: | |
1548 | |
1549 -rw-r--r-- (jim) Apr 2 23:39 file1 | |
1550 -r--r--r-- Apr 5 20:21 file2 | |
1551 @end group | |
1552 @end smallexample | |
1553 | |
1554 @noindent | |
1555 The files @samp{file1} and @samp{file2} are under version control, | |
1556 @samp{file1} is locked by user jim, and @samp{file2} is unlocked. | |
1557 | |
1558 Here is an example using CVS: | |
1559 | |
1560 @smallexample | |
1561 @group | |
1562 /home/joe/develop: | |
1563 | |
1564 -rw-r--r-- (modified) Aug 2 1997 file1.c | |
1565 -rw-r--r-- Apr 4 20:09 file2.c | |
1566 -rw-r--r-- (merge) Sep 13 1996 file3.c | |
1567 @end group | |
1568 @end smallexample | |
1569 | |
1570 Here @samp{file1.c} is modified with respect to the repository, and | |
1571 @samp{file2.c} is not. @samp{file3.c} is modified, but other changes | |
1572 have also been checked in to the repository---you need to merge them | |
1573 with the work file before you can check it in. | |
1574 | |
1575 @vindex vc-directory-exclusion-list | |
1576 When VC Dired displays subdirectories (in the ``full'' display mode), | |
1577 it omits some that should never contain any files under version control. | |
1578 By default, this includes Version Control subdirectories such as | |
1579 @samp{RCS} and @samp{CVS}; you can customize this by setting the | |
1580 variable @code{vc-directory-exclusion-list}. | |
1581 | |
1582 You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in | |
1583 ordinary Dired, that allows you to specify additional switches for the | |
1584 @samp{ls} command. | |
1585 | |
1586 @node VC Dired Commands | |
1587 @subsubsection VC Dired Commands | |
1588 | |
1589 All the usual Dired commands work normally in VC Dired mode, except | |
1590 for @kbd{v}, which is redefined as the version control prefix. You can | |
1591 invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by | |
1592 typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply | |
1593 to the file name on the current line. | |
1594 | |
1595 The command @kbd{v v} (@code{vc-next-action}) operates on all the | |
1596 marked files, so that you can lock or check in several files at once. | |
1597 If it operates on more than one file, it handles each file according to | |
1598 its current state; thus, it might lock one file, but check in another | |
1599 file. This could be confusing; it is up to you to avoid confusing | |
1600 behavior by marking a set of files that are in a similar state. | |
1601 | |
1602 If any files call for check-in, @kbd{v v} reads a single log entry, | |
1603 then uses it for all the files being checked in. This is convenient for | |
1604 registering or checking in several files at once, as part of the same | |
1605 change. | |
1606 | |
1607 @findex vc-dired-toggle-terse-mode | |
1608 @findex vc-dired-mark-locked | |
1609 You can toggle between terse display (only locked files, or files not | |
1610 up-to-date) and full display at any time by typing @kbd{v t} | |
1611 @code{vc-dired-toggle-terse-mode}. There is also a special command | |
1612 @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently | |
1613 locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l | |
1614 t k} is another way to delete from the buffer all files except those | |
1615 currently locked. | |
1616 | |
1617 @node Branches | |
1618 @subsection Multiple Branches of a File | |
1619 @cindex branch (version control) | |
1620 @cindex trunk (version control) | |
1621 | |
1622 One use of version control is to maintain multiple ``current'' | |
1623 versions of a file. For example, you might have different versions of a | |
1624 program in which you are gradually adding various unfinished new | |
1625 features. Each such independent line of development is called a | |
1626 @dfn{branch}. VC allows you to create branches, switch between | |
1627 different branches, and merge changes from one branch to another. | |
1628 Please note, however, that branches are only supported for RCS at the | |
1629 moment. | |
1630 | |
1631 A file's main line of development is usually called the @dfn{trunk}. | |
1632 The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At | |
1633 any such version, you can start an independent branch. A branch | |
1634 starting at version 1.2 would have version number 1.2.1.1, and consecutive | |
1635 versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, | |
1636 and so on. If there is a second branch also starting at version 1.2, it | |
1637 would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. | |
1638 | |
1639 @cindex head version | |
1640 If you omit the final component of a version number, that is called a | |
1641 @dfn{branch number}. It refers to the highest existing version on that | |
1642 branch---the @dfn{head version} of that branch. The branches in the | |
1643 example above have branch numbers 1.2.1 and 1.2.2. | |
1644 | |
1645 @menu | |
1646 * Switching Branches:: How to get to another existing branch. | |
1647 * Creating Branches:: How to start a new branch. | |
1648 * Merging:: Transferring changes between branches. | |
1649 * Multi-User Branching:: Multiple users working at multiple branches | |
1650 in parallel. | |
1651 @end menu | |
1652 | |
1653 @node Switching Branches | |
1654 @subsubsection Switching between Branches | |
1655 | |
1656 To switch between branches, type @kbd{C-u C-x C-q} and specify the | |
1657 version number you want to select. This version is then visited | |
1658 @emph{unlocked} (write-protected), so you can examine it before locking | |
1659 it. Switching branches in this way is allowed only when the file is not | |
1660 locked. | |
1661 | |
1662 You can omit the minor version number, thus giving only the branch | |
1663 number; this takes you to the head version on the chosen branch. If you | |
1664 only type @key{RET}, Emacs goes to the highest version on the trunk. | |
1665 | |
1666 After you have switched to any branch (including the main branch), you | |
1667 stay on it for subsequent VC commands, until you explicitly select some | |
1668 other branch. | |
1669 | |
1670 @node Creating Branches | |
1671 @subsubsection Creating New Branches | |
1672 | |
1673 To create a new branch from a head version (one that is the latest in | |
1674 the branch that contains it), first select that version if necessary, | |
1675 lock it with @kbd{C-x C-q}, and make whatever changes you want. Then, | |
1676 when you check in the changes, use @kbd{C-u C-x C-q}. This lets you | |
1677 specify the version number for the new version. You should specify a | |
1678 suitable branch number for a branch starting at the current version. | |
1679 For example, if the current version is 2.5, the branch number should be | |
1680 2.5.1, 2.5.2, and so on, depending on the number of existing branches at | |
1681 that point. | |
1682 | |
1683 To create a new branch at an older version (one that is no longer the | |
1684 head of a branch), first select that version (@pxref{Switching | |
1685 Branches}), then lock it with @kbd{C-x C-q}. You'll be asked to | |
1686 confirm, when you lock the old version, that you really mean to create a | |
1687 new branch---if you say no, you'll be offered a chance to lock the | |
1688 latest version instead. | |
1689 | |
1690 Then make your changes and type @kbd{C-x C-q} again to check in a new | |
1691 version. This automatically creates a new branch starting from the | |
1692 selected version. You need not specially request a new branch, because | |
1693 that's the only way to add a new version at a point that is not the head | |
1694 of a branch. | |
1695 | |
1696 After the branch is created, you ``stay'' on it. That means that | |
1697 subsequent check-ins create new versions on that branch. To leave the | |
1698 branch, you must explicitly select a different version with @kbd{C-u C-x | |
1699 C-q}. To transfer changes from one branch to another, use the merge | |
1700 command, described in the next section. | |
1701 | |
1702 @node Merging | |
1703 @subsubsection Merging Branches | |
1704 | |
1705 @cindex merging changes | |
1706 When you have finished the changes on a certain branch, you will | |
1707 often want to incorporate them into the file's main line of development | |
1708 (the trunk). This is not a trivial operation, because development might | |
1709 also have proceeded on the trunk, so that you must @dfn{merge} the | |
1710 changes into a file that has already been changed otherwise. VC allows | |
1711 you to do this (and other things) with the @code{vc-merge} command. | |
1712 | |
1713 @table @kbd | |
1714 @item C-x v m (vc-merge) | |
1715 Merge changes into the work file. | |
1716 @end table | |
1717 | |
1718 @kindex C-x v m | |
1719 @findex vc-merge | |
1720 @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it | |
1721 into the current version of the work file. It first asks you for a | |
1722 branch number or a pair of version numbers in the minibuffer. Then it | |
1723 finds the changes from that branch, or between the two versions you | |
1724 specified, and merges them into the current version of the current file. | |
1725 | |
1726 As an example, suppose that you have finished a certain feature on | |
1727 branch 1.3.1. In the meantime, development on the trunk has proceeded | |
1728 to version 1.5. To merge the changes from the branch to the trunk, | |
1729 first go to the head version of the trunk, by typing @kbd{C-u C-x C-q | |
1730 RET}. Version 1.5 is now current. If locking is used for the file, | |
1731 type @kbd{C-x C-q} to lock version 1.5 so that you can change it. Next, | |
1732 type @kbd{C-x v m 1.3.1 RET}. This takes the entire set of changes on | |
1733 branch 1.3.1 (relative to version 1.3, where the branch started, up to | |
1734 the last version on the branch) and merges it into the current version | |
1735 of the work file. You can now check in the changed file, thus creating | |
1736 version 1.6 containing the changes from the branch. | |
1737 | |
1738 It is possible to do further editing after merging the branch, before | |
1739 the next check-in. But it is usually wiser to check in the merged | |
1740 version, then lock it and make the further changes. This will keep | |
1741 a better record of the history of changes. | |
1742 | |
1743 @cindex conflicts | |
1744 @cindex resolving conflicts | |
1745 When you merge changes into a file that has itself been modified, the | |
1746 changes might overlap. We call this situation a @dfn{conflict}, and | |
1747 reconciling the conflicting changes is called @dfn{resolving a | |
1748 conflict}. | |
1749 | |
1750 Whenever conflicts occur during merging, VC detects them, tells you | |
1751 about them in the echo area, and asks whether you want help in merging. | |
1752 If you say yes, it starts an Ediff session (@pxref{Top, | |
1753 Ediff, Ediff, ediff, The Ediff Manual}). | |
1754 | |
1755 If you say no, the conflicting changes are both inserted into the | |
1756 file, surrounded by @dfn{conflict markers}. The example below shows how | |
1757 a conflict region looks; the file is called @samp{name} and the current | |
1758 master file version with user B's changes in it is 1.11. | |
1759 | |
1760 @c @w here is so CVS won't think this is a conflict. | |
1761 @smallexample | |
1762 @group | |
1763 @w{<}<<<<<< name | |
1764 @var{User A's version} | |
1765 ======= | |
1766 @var{User B's version} | |
1767 @w{>}>>>>>> 1.11 | |
1768 @end group | |
1769 @end smallexample | |
1770 | |
1771 @cindex vc-resolve-conflicts | |
1772 Then you can resolve the conflicts by editing the file manually. Or | |
1773 you can type @code{M-x vc-resolve-conflicts} after visiting the file. | |
1774 This starts an Ediff session, as described above. | |
1775 | |
1776 @node Multi-User Branching | |
1777 @subsubsection Multi-User Branching | |
1778 | |
1779 It is often useful for multiple developers to work simultaneously on | |
1780 different branches of a file. CVS allows this by default; for RCS, it | |
1781 is possible if you create multiple source directories. Each source | |
1782 directory should have a link named @file{RCS} which points to a common | |
1783 directory of RCS master files. Then each source directory can have its | |
1784 own choice of selected versions, but all share the same common RCS | |
1785 records. | |
1786 | |
1787 This technique works reliably and automatically, provided that the | |
1788 source files contain RCS version headers (@pxref{Version Headers}). The | |
1789 headers enable Emacs to be sure, at all times, which version number is | |
1790 present in the work file. | |
1791 | |
1792 If the files do not have version headers, you must instead tell Emacs | |
1793 explicitly in each session which branch you are working on. To do this, | |
1794 first find the file, then type @kbd{C-u C-x C-q} and specify the correct | |
1795 branch number. This ensures that Emacs knows which branch it is using | |
1796 during this particular editing session. | |
1797 | |
1798 @node Snapshots | |
1799 @subsection Snapshots | |
1800 @cindex snapshots and version control | |
1801 | |
1802 A @dfn{snapshot} is a named set of file versions (one for each | |
1803 registered file) that you can treat as a unit. One important kind of | |
1804 snapshot is a @dfn{release}, a (theoretically) stable version of the | |
1805 system that is ready for distribution to users. | |
1806 | |
1807 @menu | |
1808 * Making Snapshots:: The snapshot facilities. | |
1809 * Snapshot Caveats:: Things to be careful of when using snapshots. | |
1810 @end menu | |
1811 | |
1812 @node Making Snapshots | |
1813 @subsubsection Making and Using Snapshots | |
1814 | |
1815 There are two basic commands for snapshots; one makes a | |
1816 snapshot with a given name, the other retrieves a named snapshot. | |
1817 | |
1818 @table @code | |
1819 @kindex C-x v s | |
1820 @findex vc-create-snapshot | |
1821 @item C-x v s @var{name} @key{RET} | |
1822 Define the last saved versions of every registered file in or under the | |
1823 current directory as a snapshot named @var{name} | |
1824 (@code{vc-create-snapshot}). | |
1825 | |
1826 @kindex C-x v r | |
1827 @findex vc-retrieve-snapshot | |
1828 @item C-x v r @var{name} @key{RET} | |
1829 For all registered files at or below the current directory level, select | |
1830 whatever versions correspond to the snapshot @var{name} | |
1831 (@code{vc-retrieve-snapshot}). | |
1832 | |
1833 This command reports an error if any files are locked at or below the | |
1834 current directory, without changing anything; this is to avoid | |
1835 overwriting work in progress. | |
1836 @end table | |
1837 | |
1838 A snapshot uses a very small amount of resources---just enough to record | |
1839 the list of file names and which version belongs to the snapshot. Thus, | |
1840 you need not hesitate to create snapshots whenever they are useful. | |
1841 | |
1842 You can give a snapshot name as an argument to @kbd{C-x v =} or | |
1843 @kbd{C-x v ~} (@pxref{Old Versions}). Thus, you can use it to compare a | |
1844 snapshot against the current files, or two snapshots against each other, | |
1845 or a snapshot against a named version. | |
1846 | |
1847 @node Snapshot Caveats | |
1848 @subsubsection Snapshot Caveats | |
1849 | |
1850 @cindex named configurations (RCS) | |
1851 VC's snapshot facilities are modeled on RCS's named-configuration | |
1852 support. They use RCS's native facilities for this, so under VC | |
1853 snapshots made using RCS are visible even when you bypass VC. | |
1854 | |
1855 @c worded verbosely to avoid overfull hbox. | |
1856 For SCCS, VC implements snapshots itself. The files it uses contain | |
1857 name/file/version-number triples. These snapshots are visible only | |
1858 through VC. | |
1859 | |
1860 A snapshot is a set of checked-in versions. So make sure that all the | |
1861 files are checked in and not locked when you make a snapshot. | |
1862 | |
1863 File renaming and deletion can create some difficulties with snapshots. | |
1864 This is not a VC-specific problem, but a general design issue in version | |
1865 control systems that no one has solved very well yet. | |
1866 | |
1867 If you rename a registered file, you need to rename its master along | |
1868 with it (the command @code{vc-rename-file} does this automatically). If | |
1869 you are using SCCS, you must also update the records of the snapshot, to | |
1870 mention the file by its new name (@code{vc-rename-file} does this, | |
1871 too). An old snapshot that refers to a master file that no longer | |
1872 exists under the recorded name is invalid; VC can no longer retrieve | |
1873 it. It would be beyond the scope of this manual to explain enough about | |
1874 RCS and SCCS to explain how to update the snapshots by hand. | |
1875 | |
1876 Using @code{vc-rename-file} makes the snapshot remain valid for | |
1877 retrieval, but it does not solve all problems. For example, some of the | |
1878 files in the program probably refer to others by name. At the very | |
1879 least, the makefile probably mentions the file that you renamed. If you | |
1880 retrieve an old snapshot, the renamed file is retrieved under its new | |
1881 name, which is not the name that the makefile expects. So the program | |
1882 won't really work as retrieved. | |
1883 | |
1884 @node Miscellaneous VC | |
1885 @subsection Miscellaneous Commands and Features of VC | |
1886 | |
1887 This section explains the less-frequently-used features of VC. | |
1888 | |
1889 @menu | |
1890 * Change Logs and VC:: Generating a change log file from log entries. | |
1891 * Renaming and VC:: A command to rename both the source and master | |
1892 file correctly. | |
1893 * Version Headers:: Inserting version control headers into working files. | |
1894 @end menu | |
1895 | |
1896 @node Change Logs and VC | |
1897 @subsubsection Change Logs and VC | |
1898 | |
1899 If you use RCS or CVS for a program and also maintain a change log | |
1900 file for it (@pxref{Change Log}), you can generate change log entries | |
1901 automatically from the version control log entries: | |
1902 | |
1903 @table @kbd | |
1904 @item C-x v a | |
1905 @kindex C-x v a | |
1906 @findex vc-update-change-log | |
1907 Visit the current directory's change log file and, for registered files | |
1908 in that directory, create new entries for versions checked in since the | |
1909 most recent entry in the change log file. | |
1910 (@code{vc-update-change-log}). | |
1911 | |
1912 This command works with RCS or CVS only, not with SCCS. | |
1913 | |
1914 @item C-u C-x v a | |
1915 As above, but only find entries for the current buffer's file. | |
1916 | |
1917 @item M-1 C-x v a | |
1918 As above, but find entries for all the currently visited files that are | |
1919 maintained with version control. This works only with RCS, and it puts | |
1920 all entries in the log for the default directory, which may not be | |
1921 appropriate. | |
1922 @end table | |
1923 | |
1924 For example, suppose the first line of @file{ChangeLog} is dated | |
1925 1999-04-10, and that the only check-in since then was by Nathaniel | |
1926 Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log | |
1927 messages that start with `#'.}. Then @kbd{C-x v a} visits | |
1928 @file{ChangeLog} and inserts text like this: | |
1929 | |
1930 @iftex | |
1931 @medbreak | |
1932 @end iftex | |
1933 @smallexample | |
1934 @group | |
1935 1999-05-22 Nathaniel Bowditch <nat@@apn.org> | |
1936 | |
1937 * rcs2log: Ignore log messages that start with `#'. | |
1938 @end group | |
1939 @end smallexample | |
1940 @iftex | |
1941 @medbreak | |
1942 @end iftex | |
1943 | |
1944 @noindent | |
1945 You can then edit the new change log entry further as you wish. | |
1946 | |
1947 Unfortunately, timestamps in ChangeLog files are only dates, so some | |
1948 of the new change log entry may duplicate what's already in ChangeLog. | |
1949 You will have to remove these duplicates by hand. | |
1950 | |
1951 Normally, the log entry for file @file{foo} is displayed as @samp{* | |
1952 foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted | |
1953 if the text of the log entry starts with @w{@samp{(@var{functionname}): | |
1954 }}. For example, if the log entry for @file{vc.el} is | |
1955 @samp{(vc-do-command): Check call-process status.}, then the text in | |
1956 @file{ChangeLog} looks like this: | |
1957 | |
1958 @iftex | |
1959 @medbreak | |
1960 @end iftex | |
1961 @smallexample | |
1962 @group | |
1963 1999-05-06 Nathaniel Bowditch <nat@@apn.org> | |
1964 | |
1965 * vc.el (vc-do-command): Check call-process status. | |
1966 @end group | |
1967 @end smallexample | |
1968 @iftex | |
1969 @medbreak | |
1970 @end iftex | |
1971 | |
1972 When @kbd{C-x v a} adds several change log entries at once, it groups | |
1973 related log entries together if they all are checked in by the same | |
1974 author at nearly the same time. If the log entries for several such | |
1975 files all have the same text, it coalesces them into a single entry. | |
1976 For example, suppose the most recent check-ins have the following log | |
1977 entries: | |
1978 | |
1979 @flushleft | |
1980 @bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} | |
1981 @bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} | |
1982 @bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} | |
1983 @end flushleft | |
1984 | |
1985 @noindent | |
1986 They appear like this in @file{ChangeLog}: | |
1987 | |
1988 @iftex | |
1989 @medbreak | |
1990 @end iftex | |
1991 @smallexample | |
1992 @group | |
1993 1999-04-01 Nathaniel Bowditch <nat@@apn.org> | |
1994 | |
1995 * vc.texinfo: Fix expansion typos. | |
1996 | |
1997 * vc.el, vc-hooks.el: Don't call expand-file-name. | |
1998 @end group | |
1999 @end smallexample | |
2000 @iftex | |
2001 @medbreak | |
2002 @end iftex | |
2003 | |
2004 Normally, @kbd{C-x v a} separates log entries by a blank line, but you | |
2005 can mark several related log entries to be clumped together (without an | |
2006 intervening blank line) by starting the text of each related log entry | |
2007 with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label | |
2008 itself is not copied to @file{ChangeLog}. For example, suppose the log | |
2009 entries are: | |
2010 | |
2011 @flushleft | |
2012 @bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} | |
2013 @bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} | |
2014 @bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} | |
2015 @end flushleft | |
2016 | |
2017 @noindent | |
2018 Then the text in @file{ChangeLog} looks like this: | |
2019 | |
2020 @iftex | |
2021 @medbreak | |
2022 @end iftex | |
2023 @smallexample | |
2024 @group | |
2025 1999-04-01 Nathaniel Bowditch <nat@@apn.org> | |
2026 | |
2027 * vc.texinfo: Fix expansion typos. | |
2028 * vc.el, vc-hooks.el: Don't call expand-file-name. | |
2029 @end group | |
2030 @end smallexample | |
2031 @iftex | |
2032 @medbreak | |
2033 @end iftex | |
2034 | |
2035 A log entry whose text begins with @samp{#} is not copied to | |
2036 @file{ChangeLog}. For example, if you merely fix some misspellings in | |
2037 comments, you can log the change with an entry beginning with @samp{#} | |
2038 to avoid putting such trivia into @file{ChangeLog}. | |
2039 | |
2040 @node Renaming and VC | |
2041 @subsubsection Renaming VC Work Files and Master Files | |
2042 | |
2043 @findex vc-rename-file | |
2044 When you rename a registered file, you must also rename its master | |
2045 file correspondingly to get proper results. Use @code{vc-rename-file} | |
2046 to rename the source file as you specify, and rename its master file | |
2047 accordingly. It also updates any snapshots (@pxref{Snapshots}) that | |
2048 mention the file, so that they use the new name; despite this, the | |
2049 snapshot thus modified may not completely work (@pxref{Snapshot | |
2050 Caveats}). | |
2051 | |
2052 You cannot use @code{vc-rename-file} on a file that is locked by | |
2053 someone else. | |
2054 | |
2055 @node Version Headers | |
2056 @subsubsection Inserting Version Control Headers | |
2057 | |
2058 Sometimes it is convenient to put version identification strings | |
2059 directly into working files. Certain special strings called | |
2060 @dfn{version headers} are replaced in each successive version by the | |
2061 number of that version. | |
2062 | |
2063 If you are using RCS, and version headers are present in your working | |
2064 files, Emacs can use them to determine the current version and the | |
2065 locking state of the files. This is more reliable than referring to the | |
2066 master files, which is done when there are no version headers. Note | |
2067 that in a multi-branch environment, version headers are necessary to | |
2068 make VC behave correctly (@pxref{Multi-User Branching}). | |
2069 | |
2070 Searching for version headers is controlled by the variable | |
2071 @code{vc-consult-headers}. If it is non-@code{nil}, Emacs searches for | |
2072 headers to determine the version number you are editing. Setting it to | |
2073 @code{nil} disables this feature. | |
2074 | |
2075 @kindex C-x v h | |
2076 @findex vc-insert-headers | |
2077 You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to | |
2078 insert a suitable header string. | |
2079 | |
2080 @table @kbd | |
2081 @item C-x v h | |
2082 Insert headers in a file for use with your version-control system. | |
2083 @end table | |
2084 | |
2085 @vindex vc-header-alist | |
2086 The default header string is @samp{@w{$}Id$} for RCS and | |
2087 @samp{@w{%}W%} for SCCS. You can specify other headers to insert by | |
2088 setting the variable @code{vc-header-alist}. Its value is a list of | |
2089 elements of the form @code{(@var{program} . @var{string})} where | |
2090 @var{program} is @code{RCS} or @code{SCCS} and @var{string} is the | |
2091 string to use. | |
2092 | |
2093 Instead of a single string, you can specify a list of strings; then | |
2094 each string in the list is inserted as a separate header on a line of | |
2095 its own. | |
2096 | |
2097 It is often necessary to use ``superfluous'' backslashes when writing | |
2098 the strings that you put in this variable. This is to prevent the | |
2099 string in the constant from being interpreted as a header itself if the | |
2100 Emacs Lisp file containing it is maintained with version control. | |
2101 | |
2102 @vindex vc-comment-alist | |
2103 Each header is inserted surrounded by tabs, inside comment delimiters, | |
2104 on a new line at point. Normally the ordinary comment | |
2105 start and comment end strings of the current mode are used, but for | |
2106 certain modes, there are special comment delimiters for this purpose; | |
2107 the variable @code{vc-comment-alist} specifies them. Each element of | |
2108 this list has the form @code{(@var{mode} @var{starter} @var{ender})}. | |
2109 | |
2110 @vindex vc-static-header-alist | |
2111 The variable @code{vc-static-header-alist} specifies further strings | |
2112 to add based on the name of the buffer. Its value should be a list of | |
2113 elements of the form @code{(@var{regexp} . @var{format})}. Whenever | |
2114 @var{regexp} matches the buffer name, @var{format} is inserted as part | |
2115 of the header. A header line is inserted for each element that matches | |
2116 the buffer name, and for each string specified by | |
2117 @code{vc-header-alist}. The header line is made by processing the | |
2118 string from @code{vc-header-alist} with the format taken from the | |
2119 element. The default value for @code{vc-static-header-alist} is as follows: | |
2120 | |
2121 @example | |
2122 @group | |
2123 (("\\.c$" . | |
2124 "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ | |
2125 #endif /* lint */\n")) | |
2126 @end group | |
2127 @end example | |
2128 | |
2129 @noindent | |
2130 It specifies insertion of text of this form: | |
2131 | |
2132 @example | |
2133 @group | |
2134 | |
2135 #ifndef lint | |
2136 static char vcid[] = "@var{string}"; | |
2137 #endif /* lint */ | |
2138 @end group | |
2139 @end example | |
2140 | |
2141 @noindent | |
2142 Note that the text above starts with a blank line. | |
2143 | |
2144 If you use more than one version header in a file, put them close | |
2145 together in the file. The mechanism in @code{revert-buffer} that | |
2146 preserves markers may not handle markers positioned between two version | |
2147 headers. | |
2148 | |
2149 @node Customizing VC | |
2150 @subsection Customizing VC | |
2151 | |
2152 There are many ways of customizing VC. The options you can set fall | |
2153 into four categories, described in the following sections. | |
2154 | |
2155 @menu | |
2156 * Backend Options:: Customizing the back-end to your needs. | |
2157 * VC Workfile Handling:: Various options concerning working files. | |
2158 * VC Status Retrieval:: How VC finds the version control status of a file, | |
2159 and how to customize this. | |
2160 * VC Command Execution:: Which commands VC should run, and how. | |
2161 @end menu | |
2162 | |
2163 @node Backend Options | |
2164 @subsubsection Options for VC Backends | |
2165 | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2166 @vindex vc-handled-backends |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2167 By default, VC detects automatically which files are managed by RCS, |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2168 which by CVS, and which by SCCS, and it tries to do the right thing in |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2169 all three cases. If you want VC to ignore one or more of these |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2170 backends, set @code{vc-handled-backends} to the list of backends that |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2171 @emph{should} be handled. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2172 |
25829 | 2173 @cindex backend options (VC) |
2174 @cindex locking under version control | |
2175 You can tell RCS and CVS whether to use locking for a file or not | |
2176 (@pxref{VC Concepts}, for a description of locking). VC automatically | |
2177 recognizes what you have chosen, and behaves accordingly. | |
2178 | |
2179 @cindex non-strict locking (RCS) | |
2180 @cindex locking, non-strict (RCS) | |
2181 For RCS, the default is to use locking, but there is a mode called | |
2182 @dfn{non-strict locking} in which you can check-in changes without | |
2183 locking the file first. Use @samp{rcs -U} to switch to non-strict | |
2184 locking for a particular file, see the @samp{rcs} manpage for details. | |
2185 | |
2186 @cindex locking (CVS) | |
2187 Under CVS, the default is not to use locking; anyone can change a work | |
2188 file at any time. However, there are ways to restrict this, resulting | |
2189 in behavior that resembles locking. | |
2190 | |
2191 @cindex CVSREAD environment variable (CVS) | |
29107 | 2192 For one thing, you can set the @env{CVSREAD} environment variable to |
25829 | 2193 an arbitrary value. If this variable is defined, CVS makes your work |
2194 files read-only by default. In Emacs, you must type @kbd{C-x C-q} to | |
2195 make the file writeable, so that editing works in fact similar as if | |
2196 locking was used. Note however, that no actual locking is performed, so | |
2197 several users can make their files writeable at the same time. When | |
29107 | 2198 setting @env{CVSREAD} for the first time, make sure to check out all |
25829 | 2199 your modules anew, so that the file protections are set correctly. |
2200 | |
2201 @cindex cvs watch feature | |
2202 @cindex watching files (CVS) | |
2203 Another way to achieve something similar to locking is to use the | |
2204 @dfn{watch} feature of CVS. If a file is being watched, CVS makes it | |
2205 read-only by default, and you must also use @kbd{C-x C-q} in Emacs to | |
2206 make it writable. VC calls @code{cvs edit} to make the file writeable, | |
2207 and CVS takes care to notify other developers of the fact that you | |
2208 intend to change the file. See the CVS documentation for details on | |
2209 using the watch feature. | |
2210 | |
2211 @node VC Workfile Handling | |
2212 @subsubsection VC Workfile Handling | |
2213 | |
2214 @vindex vc-make-backup-files | |
2215 Emacs normally does not save backup files for source files that are | |
2216 maintained with version control. If you want to make backup files even | |
2217 for files that use version control, set the variable | |
2218 @code{vc-make-backup-files} to a non-@code{nil} value. | |
2219 | |
2220 @vindex vc-keep-workfiles | |
2221 Normally the work file exists all the time, whether it is locked or | |
2222 not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking | |
2223 in a new version with @kbd{C-x C-q} deletes the work file; but any | |
2224 attempt to visit the file with Emacs creates it again. (With CVS, work | |
2225 files are always kept.) | |
2226 | |
2227 @vindex vc-follow-symlinks | |
2228 Editing a version-controlled file through a symbolic link can be | |
2229 dangerous. It bypasses the version control system---you can edit the | |
2230 file without locking it, and fail to check your changes in. Also, | |
2231 your changes might overwrite those of another user. To protect against | |
2232 this, VC checks each symbolic link that you visit, to see if it points | |
2233 to a file under version control. | |
2234 | |
2235 The variable @code{vc-follow-symlinks} controls what to do when a | |
2236 symbolic link points to a version-controlled file. If it is @code{nil}, | |
2237 VC only displays a warning message. If it is @code{t}, VC automatically | |
2238 follows the link, and visits the real file instead, telling you about | |
2239 this in the echo area. If the value is @code{ask} (the default), VC | |
2240 asks you each time whether to follow the link. | |
2241 | |
2242 @node VC Status Retrieval | |
2243 @subsubsection VC Status Retrieval | |
2244 @c There is no need to tell users about vc-master-templates. | |
2245 | |
2246 When deducing the locked/unlocked state of a file, VC first looks for | |
2247 an RCS version header string in the file (@pxref{Version Headers}). If | |
2248 there is no header string, or if you are using SCCS, VC normally looks | |
2249 at the file permissions of the work file; this is fast. But there might | |
2250 be situations when the file permissions cannot be trusted. In this case | |
2251 the master file has to be consulted, which is rather expensive. Also | |
2252 the master file can only tell you @emph{if} there's any lock on the | |
2253 file, but not whether your work file really contains that locked | |
2254 version. | |
2255 | |
2256 @vindex vc-consult-headers | |
2257 You can tell VC not to use version headers to determine lock status by | |
2258 setting @code{vc-consult-headers} to @code{nil}. VC then always uses | |
2259 the file permissions (if it can trust them), or else checks the master | |
2260 file. | |
2261 | |
2262 @vindex vc-mistrust-permissions | |
2263 You can specify the criterion for whether to trust the file | |
2264 permissions by setting the variable @code{vc-mistrust-permissions}. Its | |
2265 value can be @code{t} (always mistrust the file permissions and check | |
2266 the master file), @code{nil} (always trust the file permissions), or a | |
2267 function of one argument which makes the decision. The argument is the | |
2268 directory name of the @file{RCS}, @file{CVS} or @file{SCCS} | |
2269 subdirectory. A non-@code{nil} value from the function says to mistrust | |
2270 the file permissions. If you find that the file permissions of work | |
2271 files are changed erroneously, set @code{vc-mistrust-permissions} to | |
2272 @code{t}. Then VC always checks the master file to determine the file's | |
2273 status. | |
2274 | |
2275 @node VC Command Execution | |
2276 @subsubsection VC Command Execution | |
2277 | |
2278 @vindex vc-suppress-confirm | |
2279 If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q} | |
2280 and @kbd{C-x v i} can save the current buffer without asking, and | |
2281 @kbd{C-x v u} also operates without asking for confirmation. (This | |
2282 variable does not affect @kbd{C-x v c}; that operation is so drastic | |
2283 that it should always ask for confirmation.) | |
2284 | |
2285 @vindex vc-command-messages | |
2286 VC mode does much of its work by running the shell commands for RCS, | |
2287 CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC | |
2288 displays messages to indicate which shell commands it runs, and | |
2289 additional messages when the commands finish. | |
2290 | |
2291 @vindex vc-path | |
2292 You can specify additional directories to search for version control | |
2293 programs by setting the variable @code{vc-path}. These directories are | |
2294 searched before the usual search path. But the proper files are usually | |
2295 found automatically. | |
2296 | |
2297 @node Directories | |
2298 @section File Directories | |
2299 | |
2300 @cindex file directory | |
2301 @cindex directory listing | |
2302 The file system groups files into @dfn{directories}. A @dfn{directory | |
2303 listing} is a list of all the files in a directory. Emacs provides | |
2304 commands to create and delete directories, and to make directory | |
2305 listings in brief format (file names only) and verbose format (sizes, | |
2306 dates, and authors included). There is also a directory browser called | |
2307 Dired; see @ref{Dired}. | |
2308 | |
2309 @table @kbd | |
2310 @item C-x C-d @var{dir-or-pattern} @key{RET} | |
2311 Display a brief directory listing (@code{list-directory}). | |
2312 @item C-u C-x C-d @var{dir-or-pattern} @key{RET} | |
2313 Display a verbose directory listing. | |
2314 @item M-x make-directory @key{RET} @var{dirname} @key{RET} | |
2315 Create a new directory named @var{dirname}. | |
2316 @item M-x delete-directory @key{RET} @var{dirname} @key{RET} | |
2317 Delete the directory named @var{dirname}. It must be empty, | |
2318 or you get an error. | |
2319 @end table | |
2320 | |
2321 @findex list-directory | |
2322 @kindex C-x C-d | |
2323 The command to display a directory listing is @kbd{C-x C-d} | |
2324 (@code{list-directory}). It reads using the minibuffer a file name | |
2325 which is either a directory to be listed or a wildcard-containing | |
2326 pattern for the files to be listed. For example, | |
2327 | |
2328 @example | |
2329 C-x C-d /u2/emacs/etc @key{RET} | |
2330 @end example | |
2331 | |
2332 @noindent | |
2333 lists all the files in directory @file{/u2/emacs/etc}. Here is an | |
2334 example of specifying a file name pattern: | |
2335 | |
2336 @example | |
2337 C-x C-d /u2/emacs/src/*.c @key{RET} | |
2338 @end example | |
2339 | |
2340 Normally, @kbd{C-x C-d} prints a brief directory listing containing | |
2341 just file names. A numeric argument (regardless of value) tells it to | |
2342 make a verbose listing including sizes, dates, and authors (like | |
2343 @samp{ls -l}). | |
2344 | |
2345 @vindex list-directory-brief-switches | |
2346 @vindex list-directory-verbose-switches | |
2347 The text of a directory listing is obtained by running @code{ls} in an | |
2348 inferior process. Two Emacs variables control the switches passed to | |
2349 @code{ls}: @code{list-directory-brief-switches} is a string giving the | |
2350 switches to use in brief listings (@code{"-CF"} by default), and | |
2351 @code{list-directory-verbose-switches} is a string giving the switches to | |
2352 use in a verbose listing (@code{"-l"} by default). | |
2353 | |
2354 @node Comparing Files | |
2355 @section Comparing Files | |
2356 @cindex comparing files | |
2357 | |
2358 @findex diff | |
2359 @vindex diff-switches | |
2360 The command @kbd{M-x diff} compares two files, displaying the | |
2361 differences in an Emacs buffer named @samp{*Diff*}. It works by running | |
2362 the @code{diff} program, using options taken from the variable | |
2363 @code{diff-switches}, whose value should be a string. | |
2364 | |
2365 The buffer @samp{*Diff*} has Compilation mode as its major mode, so | |
2366 you can use @kbd{C-x `} to visit successive changed locations in the two | |
2367 source files. You can also move to a particular hunk of changes and | |
2368 type @key{RET} or @kbd{C-c C-c}, or click @kbd{Mouse-2} on it, to move | |
2369 to the corresponding source location. You can also use the other | |
2370 special commands of Compilation mode: @key{SPC} and @key{DEL} for | |
2371 scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion. | |
2372 @xref{Compilation}. | |
2373 | |
2374 @findex diff-backup | |
2375 The command @kbd{M-x diff-backup} compares a specified file with its most | |
2376 recent backup. If you specify the name of a backup file, | |
2377 @code{diff-backup} compares it with the source file that it is a backup | |
2378 of. | |
2379 | |
2380 @findex compare-windows | |
2381 The command @kbd{M-x compare-windows} compares the text in the current | |
2382 window with that in the next window. Comparison starts at point in each | |
2383 window, and each starting position is pushed on the mark ring in its | |
2384 respective buffer. Then point moves forward in each window, a character | |
2385 at a time, until a mismatch between the two windows is reached. Then | |
2386 the command is finished. For more information about windows in Emacs, | |
2387 @ref{Windows}. | |
2388 | |
2389 @vindex compare-ignore-case | |
2390 With a numeric argument, @code{compare-windows} ignores changes in | |
2391 whitespace. If the variable @code{compare-ignore-case} is | |
2392 non-@code{nil}, it ignores differences in case as well. | |
2393 | |
31076 | 2394 @findex diff-mode |
2395 @cindex diffs | |
2396 @cindex patches | |
2397 @cindex Diff mode | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2398 Differences between versions of files are often distributed as |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2399 @dfn{patches}, which are the output from @command{diff} or a version |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2400 control system that uses @command{diff}. @kbd{M-x diff-mode} turns on |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2401 Diff mode, a major mode for viewing and editing patches, either as |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2402 ``unified diffs'' or ``context diffs.'' |
31076 | 2403 |
2404 @cindex Smerge mode | |
2405 @findex smerge-mode | |
2406 @cindex failed merges | |
2407 @cindex merges, failed | |
2408 @pindex diff3 | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2409 You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2410 mode for editing output from the @command{diff3} program. This is |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2411 typically the result of a failed merge from a version control system |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2412 ``update'' outside VC, due to conflicting changes to a file. Smerge |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2413 mode provides commands to resolve conflicts by selecting specific |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2414 changes. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2415 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2416 See also @ref{Emerge}, and @ref{Top,,, ediff, The Ediff Manual}, for |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2417 convenient facilities for merging two similar files. |
25829 | 2418 |
2419 @node Misc File Ops | |
2420 @section Miscellaneous File Operations | |
2421 | |
2422 Emacs has commands for performing many other operations on files. | |
2423 All operate on one file; they do not accept wildcard file names. | |
2424 | |
2425 @findex view-file | |
2426 @cindex viewing | |
2427 @cindex View mode | |
2428 @cindex mode, View | |
2429 @kbd{M-x view-file} allows you to scan or read a file by sequential | |
2430 screenfuls. It reads a file name argument using the minibuffer. After | |
2431 reading the file into an Emacs buffer, @code{view-file} displays the | |
2432 beginning. You can then type @key{SPC} to scroll forward one windowful, | |
2433 or @key{DEL} to scroll backward. Various other commands are provided | |
2434 for moving around in the file, but none for changing it; type @kbd{?} | |
2435 while viewing for a list of them. They are mostly the same as normal | |
2436 Emacs cursor motion commands. To exit from viewing, type @kbd{q}. | |
2437 The commands for viewing are defined by a special major mode called View | |
2438 mode. | |
2439 | |
2440 A related command, @kbd{M-x view-buffer}, views a buffer already present | |
2441 in Emacs. @xref{Misc Buffer}. | |
2442 | |
2443 @findex insert-file | |
2444 @kbd{M-x insert-file} inserts a copy of the contents of the specified | |
2445 file into the current buffer at point, leaving point unchanged before the | |
2446 contents and the mark after them. | |
2447 | |
2448 @findex write-region | |
2449 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it | |
2450 copies the contents of the region into the specified file. @kbd{M-x | |
2451 append-to-file} adds the text of the region to the end of the specified | |
2452 file. @xref{Accumulating Text}. | |
2453 | |
2454 @findex delete-file | |
2455 @cindex deletion (of files) | |
2456 @kbd{M-x delete-file} deletes the specified file, like the @code{rm} | |
2457 command in the shell. If you are deleting many files in one directory, it | |
2458 may be more convenient to use Dired (@pxref{Dired}). | |
2459 | |
2460 @findex rename-file | |
2461 @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using | |
2462 the minibuffer, then renames file @var{old} as @var{new}. If a file named | |
2463 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not | |
2464 done; this is because renaming causes the old meaning of the name @var{new} | |
2465 to be lost. If @var{old} and @var{new} are on different file systems, the | |
2466 file @var{old} is copied and deleted. | |
2467 | |
2468 @findex add-name-to-file | |
2469 The similar command @kbd{M-x add-name-to-file} is used to add an | |
2470 additional name to an existing file without removing its old name. | |
2471 The new name must belong on the same file system that the file is on. | |
2472 | |
2473 @findex copy-file | |
2474 @cindex copying files | |
2475 @kbd{M-x copy-file} reads the file @var{old} and writes a new file named | |
2476 @var{new} with the same contents. Confirmation is required if a file named | |
2477 @var{new} already exists, because copying has the consequence of overwriting | |
2478 the old contents of the file @var{new}. | |
2479 | |
2480 @findex make-symbolic-link | |
2481 @kbd{M-x make-symbolic-link} reads two file names @var{target} and | |
2482 @var{linkname}, then creates a symbolic link named @var{linkname} and | |
2483 pointing at @var{target}. The effect is that future attempts to open file | |
2484 @var{linkname} will refer to whatever file is named @var{target} at the | |
2485 time the opening is done, or will get an error if the name @var{target} is | |
2486 not in use at that time. This command does not expand the argument | |
2487 @var{target}, so that it allows you to specify a relative name | |
2488 as the target of the link. | |
2489 | |
2490 Confirmation is required when creating the link if @var{linkname} is | |
2491 in use. Note that not all systems support symbolic links. | |
2492 | |
2493 @node Compressed Files | |
2494 @section Accessing Compressed Files | |
2495 @cindex compression | |
2496 @cindex uncompression | |
2497 @cindex Auto Compression mode | |
2498 @cindex mode, Auto Compression | |
2499 @pindex gzip | |
2500 | |
2501 @findex auto-compression-mode | |
28123
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2502 @vindex auto-compression-mode |
25829 | 2503 Emacs comes with a library that can automatically uncompress |
2504 compressed files when you visit them, and automatically recompress them | |
2505 if you alter them and save them. To enable this feature, type the | |
28123
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2506 command @kbd{M-x auto-compression-mode}. You can enable it permanently |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2507 by customizing the option @var{auto-compression-mode}. |
25829 | 2508 |
2509 When automatic compression (which implies automatic uncompression as | |
2510 well) is enabled, Emacs recognizes compressed files by their file names. | |
2511 File names ending in @samp{.gz} indicate a file compressed with | |
2512 @code{gzip}. Other endings indicate other compression programs. | |
2513 | |
2514 Automatic uncompression and compression apply to all the operations in | |
2515 which Emacs uses the contents of a file. This includes visiting it, | |
2516 saving it, inserting its contents into a buffer, loading it, and byte | |
2517 compiling it. | |
2518 | |
28123
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2519 @node File Archives |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2520 @section File Archives |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2521 @cindex mode, tar |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2522 @cindex Tar mode |
29683
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2523 @pindex tar |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2524 |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2525 A file whose name ends in @samp{.tar} is normally an @dfn{archive} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2526 made by the @code{tar} program. Emacs views these files in a special |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2527 mode called Tar mode which provides a Dired-like list of the contents |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2528 (@pxref{Dired}). You can move around through the list just as you |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2529 would in Dired, and visit the subfiles contained in the archive. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2530 However, not all Dired commands are available in Tar mode. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2531 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2532 If you enable Auto Compression mode (@pxref{Compressed Files}), then |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2533 Tar mode is used also for compressed archives---files with extensions |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2534 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. |
29683
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2535 |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2536 The keys @kbd{e}, @kbd{f} and @kbd{RET} all extract a component file |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2537 into its own buffer. You can edit it there and when you save the buffer |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2538 the edited version will replace the version in the Tar buffer. @kbd{v} |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2539 extracts a file into a buffer in View mode. @kbd{o} extracts the file |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2540 and displays it in another window, so you could edit the file and |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2541 operate on the archive simultaneously. @kbd{d} marks a file for |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2542 deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2543 Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2544 renames a file. @kbd{g} reverts the buffer from the archive on disk. |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2545 |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2546 The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2547 bits, group, and owner, respectively. |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2548 |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2549 If your display supports colors and the mouse, moving the mouse |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2550 pointer across a file name highlights that file name, indicating that |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2551 you can click on it. Clicking @kbd{Mouse-2} on the highlighted file |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2552 name extracts the file into a buffer and displays that buffer. |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2553 |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2554 Saving the Tar buffer writes a new version of the archive to disk with |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2555 the changes you made to the components. |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2556 |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2557 You don't need the @code{tar} program to use Tar mode---Emacs reads |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2558 the archives directly. However, accessing compressed archives |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2559 requires the appropriate uncompression program. |
31076 | 2560 |
28123
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2561 @cindex Archive mode |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2562 @cindex mode, archive |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2563 @cindex @code{arc} |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2564 @cindex @code{jar} |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2565 @cindex @code{zip} |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2566 @cindex @code{lzh} |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2567 @cindex @code{zoo} |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2568 @pindex arc |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2569 @pindex jar |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2570 @pindex zip |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2571 @pindex lzh |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2572 @pindex zoo |
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2573 @cindex Java class archives |
29683
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2574 @cindex unzip archives |
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2575 A separate but similar Archive mode is used for archives produced by |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2576 the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2577 @code{zoo}, which have extensions corresponding to the program names. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2578 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2579 The keybindings of Archive mode are similar to those in Tar mode, |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2580 with the addition of the @kbd{m} key which marks a file for subsequent |
29683
324386e590b7
(File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents:
29556
diff
changeset
|
2581 operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2582 Also, the @kbd{a} key toggles the display of detailed file |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2583 information, for those archive types where it won't fit in a single |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2584 line. Operations such as renaming a subfile, or changing its mode or |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2585 owner, are supported only for some of the archive formats. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2586 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2587 Unlike Tar mode, Archive mode runs the archiving program to unpack |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2588 and repack archives. Details of the program names and their options |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2589 can be set in the @samp{Archive} Customize group. However, you don't |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2590 need these programs to the archive table of contents, only to extract |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2591 or manipulate the subfiles in the archive. |
28123
6e2e72ee55a6
(Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents:
26105
diff
changeset
|
2592 |
25829 | 2593 @node Remote Files |
2594 @section Remote Files | |
2595 | |
2596 @cindex FTP | |
2597 @cindex remote file access | |
2598 You can refer to files on other machines using a special file name syntax: | |
2599 | |
2600 @example | |
2601 @group | |
2602 /@var{host}:@var{filename} | |
2603 /@var{user}@@@var{host}:@var{filename} | |
26105 | 2604 /@var{user}@@@var{host}#@var{port}:@var{filename} |
25829 | 2605 @end group |
2606 @end example | |
2607 | |
2608 @noindent | |
2609 When you do this, Emacs uses the FTP program to read and write files on | |
2610 the specified host. It logs in through FTP using your user name or the | |
2611 name @var{user}. It may ask you for a password from time to time; this | |
26105 | 2612 is used for logging in on @var{host}. The form using @var{port} allows |
2613 you to access servers running on a non-default TCP port. | |
25829 | 2614 |
35908
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2615 @cindex backups for remote files |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2616 @vindex ange-ftp-make-backup-files |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2617 If you want to disable backups for remote files, set the variable |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2618 @code{ange-ftp-make-backup-files} to @code{nil}. |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2619 |
25829 | 2620 @cindex ange-ftp |
2621 @vindex ange-ftp-default-user | |
35908
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2622 @cindex user name for remote file access |
25829 | 2623 Normally, if you do not specify a user name in a remote file name, |
2624 that means to use your own user name. But if you set the variable | |
2625 @code{ange-ftp-default-user} to a string, that string is used instead. | |
2626 (The Emacs package that implements FTP file access is called | |
2627 @code{ange-ftp}.) | |
2628 | |
35908
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2629 @cindex anonymous FTP |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2630 @vindex ange-ftp-generate-anonymous-password |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2631 To visit files accessible by anonymous FTP, you use special user |
36155
3594ca3f5f64
Fix some Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
36136
diff
changeset
|
2632 names @samp{anonymous} or @samp{ftp}. Passwords for these user names |
3594ca3f5f64
Fix some Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
36136
diff
changeset
|
2633 are handled specially. The variable |
35908
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2634 @code{ange-ftp-generate-anonymous-password} controls what happens: if |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2635 the value of this variable is a string, then that string is used as |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2636 the password; if non-@code{nil} (the default), then the value of |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2637 @code{user-mail-address} is used; if @code{nil}, the user is prompted |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2638 for a password as normal. |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2639 |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2640 @cindex firewall, and accessing remote files |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2641 @cindex gateway, and remote file access with @code{ange-ftp} |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2642 @vindex ange-ftp-smart-gateway |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2643 @vindex ange-ftp-gateway-host |
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2644 Sometimes you may be unable to access files on a remote machine |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2645 because a @dfn{firewall} in between blocks the connection for security |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2646 reasons. If you can log in on a @dfn{gateway} machine from which the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2647 target files @emph{are} accessible, and whose FTP server supports |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2648 gatewaying features, you can still use remote file names; all you have |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2649 to do is specify the name of the gateway machine by setting the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2650 variable @code{ange-ftp-gateway-host}, and set |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2651 @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2652 to make remote file names work, but the procedure is complex. You can |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2653 read the instructions by typing @kbd{M-x finder-commentary @key{RET} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2654 ange-ftp @key{RET}}. |
35908
4ba2a6029c03
(Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents:
35731
diff
changeset
|
2655 |
25829 | 2656 @vindex file-name-handler-alist |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2657 @cindex disabling remote files |
26105 | 2658 You can entirely turn off the FTP file name feature by removing the |
2659 entries @var{ange-ftp-completion-hook-function} and | |
2660 @var{ange-ftp-hook-function} from the variable | |
28327
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
2661 @code{file-name-handler-alist}. You can turn off the feature in |
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
2662 individual cases by quoting the file name with @samp{/:} (@pxref{Quoted |
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
2663 File Names}). |
25829 | 2664 |
2665 @node Quoted File Names | |
2666 @section Quoted File Names | |
2667 | |
2668 @cindex quoting file names | |
2669 You can @dfn{quote} an absolute file name to prevent special | |
2670 characters and syntax in it from having their special effects. | |
2671 The way to do this is to add @samp{/:} at the beginning. | |
2672 | |
2673 For example, you can quote a local file name which appears remote, to | |
2674 prevent it from being treated as a remote file name. Thus, if you have | |
2675 a directory named @file{/foo:} and a file named @file{bar} in it, you | |
2676 can refer to that file in Emacs as @samp{/:/foo:/bar}. | |
2677 | |
2678 @samp{/:} can also prevent @samp{~} from being treated as a special | |
2679 character for a user's home directory. For example, @file{/:/tmp/~hack} | |
2680 refers to a file whose name is @file{~hack} in directory @file{/tmp}. | |
2681 | |
2682 Likewise, quoting with @samp{/:} is one way to enter in the minibuffer | |
2683 a file name that contains @samp{$}. However, the @samp{/:} must be at | |
2684 the beginning of the buffer in order to quote @samp{$}. | |
2685 | |
28327
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
2686 @cindex wildcard characters in file names |
25829 | 2687 You can also quote wildcard characters with @samp{/:}, for visiting. |
2688 For example, @file{/:/tmp/foo*bar} visits the file @file{/tmp/foo*bar}. | |
2689 However, in most cases you can simply type the wildcard characters for | |
2690 themselves. For example, if the only file name in @file{/tmp} that | |
2691 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, then | |
2692 specifying @file{/tmp/foo*bar} will visit just @file{/tmp/foo*bar}. | |
28327
f7b17a6af3db
(Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents:
28123
diff
changeset
|
2693 Another way is to specify @file{/tmp/foo[*]bar}. |
28526
297e03ccd7e6
(Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents:
28327
diff
changeset
|
2694 |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2695 @node File Name Cache |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2696 @section File Name Cache |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2697 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2698 @cindex file name caching |
28671 | 2699 @cindex cache of file names |
2700 @pindex find | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2701 @kindex C-@key{TAB} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2702 @findex file-cache-minibuffer-complete |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2703 You can use the @dfn{file name cache} to make it easy to locate a |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2704 file by name, without having to remember exactly where it is located. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2705 When typing a file name in the minibuffer, @kbd{C-@key{tab}} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2706 (@code{file-cache-minibuffer-complete}) completes it using the file |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2707 name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2708 possible completions of what you had originally typed. Note that the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2709 @kbd{C-@key{tab}} character cannot be typed on most text-only |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2710 terminals. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2711 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2712 The file name cache does not fill up automatically. Instead, you |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2713 load file names into the cache using these commands: |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2714 |
31076 | 2715 @findex file-cache-add-directory |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2716 @table @kbd |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2717 @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2718 Add each file name in @var{directory} to the file name cache. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2719 @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2720 Add each file name in @var{directory} and all of its nested |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2721 subdirectories to the file name cache. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2722 @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2723 Add each file name in @var{directory} and all of its nested |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2724 subdirectories to the file name cache, using @command{locate} to find |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2725 them all. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2726 @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2727 Add each file name in each directory listed in @var{variable} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2728 to the file name cache. @var{variable} should be a Lisp variable |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2729 such as @code{load-path} or @code{exec-path}, whose value is a list |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2730 of directory names. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2731 @item M-x file-cache-clear-cache @key{RET} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2732 Clear the cache; that is, remove all file names from it. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2733 @end table |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2734 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2735 @node File Conveniences |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2736 @section Convenience Features for Finding Files |
31076 | 2737 |
2738 @findex recentf-mode | |
2739 @vindex recentf-mode | |
2740 @findex recentf-save-list | |
2741 @findex recentf-edit-list | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2742 If you enable Recentf mode, with @kbd{M-x recentf-mode}, the |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2743 @samp{Files} menu includes a submenu containing a list of recently |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2744 opened files. @kbd{M-x recentf-save-list} saves the current |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2745 recent-file-list to a file, and @kbd{M-x recentf-edit-list} edits it. |
32221 | 2746 |
2747 @findex auto-image-file-mode | |
2748 @findex mode, auto-image-file | |
2749 @cindex images, visiting | |
2750 @cindex visiting image files | |
2751 @vindex image-file-name-regexps | |
2752 @vindex image-file-name-extensions | |
36136
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2753 When Auto-image-file minor mode is enabled, visiting an image file |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2754 displays it as an image, not as text. Likewise, inserting an image |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2755 file into a buffer inserts it as an image. This works only when Emacs |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2756 can display the relevant image type. The variables |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2757 @code{image-file-name-extensions} or @code{image-file-name-regexps} |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2758 control which file names are recognized as containing images. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2759 |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2760 The @kbd{M-x ffap} command generalizes @code{find-file} with more |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2761 powerful heuristic defaults (@pxref{FFAP}), often based on the text at |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2762 point. Partial Completion mode offers other features extending |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2763 @code{find-file}, which can be used with @code{ffap}. |
a5ae50ec6fe7
Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents:
35919
diff
changeset
|
2764 @xref{Completion Options}. |