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