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