428
+ − 1
+ − 2 @node Files, Buffers, Fixit, Top
+ − 3 @chapter File Handling
+ − 4 @cindex files
+ − 5
+ − 6 The basic unit of stored data in Unix is the @dfn{file}. To edit a file,
+ − 7 you must tell Emacs to examine the file and prepare a buffer containing a
+ − 8 copy of the file's text. This is called @dfn{visiting} the file. Editing
+ − 9 commands apply directly to text in the buffer; that is, to the copy inside
+ − 10 Emacs. Your changes appear in the file itself only when you @dfn{save} the
+ − 11 buffer back into the file.
+ − 12
741
+ − 13 @cindex files, remote
+ − 14 @cindex remote files
+ − 15 Emacs is also able to handle ``remote files'' which are stored on
+ − 16 other hosts. Not only is Emacs somewhat aware of the special issues
+ − 17 involved with network file systems, but it can also use FTP and ssh (or
+ − 18 rsh) to make local copies of the files, and refresh them on the remote
+ − 19 host automatically when you save the buffer. The FTP interface is
+ − 20 provided by the standard @samp{efs} package @ref{Top, EFS, , efs}. The
+ − 21 ssh/rsh interface is provided by the optional @samp{tramp} package
+ − 22 @ref{Top, TRAMP, , tramp}. These packages attempt to implement all of
+ − 23 the operations described below, making remote file use transparent
+ − 24 (except for unavoidable network delays).
+ − 25
428
+ − 26 In addition to visiting and saving files, Emacs can delete, copy, rename,
+ − 27 and append to files, and operate on file directories.
+ − 28
+ − 29 @menu
+ − 30 * File Names:: How to type and edit file name arguments.
+ − 31 * Visiting:: Visiting a file prepares Emacs to edit the file.
+ − 32 * Saving:: Saving makes your changes permanent.
+ − 33 * Reverting:: Reverting cancels all the changes not saved.
+ − 34 * Auto Save:: Auto Save periodically protects against loss of data.
+ − 35 * Version Control:: Version control systems (RCS and SCCS).
+ − 36 * ListDir:: Listing the contents of a file directory.
+ − 37 * Comparing Files:: Finding where two files differ.
+ − 38 * Dired:: ``Editing'' a directory to delete, rename, etc.
+ − 39 the files in it.
+ − 40 * Misc File Ops:: Other things you can do on files.
+ − 41 @end menu
+ − 42
+ − 43 @node File Names, Visiting, Files, Files
+ − 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.) File names are specified in the minibuffer
+ − 50 (@pxref{Minibuffer}). @dfn{Completion} is available, to make it easier to
+ − 51 specify long file names. @xref{Completion}.
+ − 52
+ − 53 There is always a @dfn{default file name} which is used if you
+ − 54 enter an empty argument by typing just @key{RET}. Normally the default
+ − 55 file name is the name of the file visited in the current buffer; this
+ − 56 makes it easy to operate on that file with any of the Emacs file
+ − 57 commands.
+ − 58
741
+ − 59 The syntax for accessing remote files unfortunately varies depending on
+ − 60 the method used. The syntax for using FTP is
+ − 61 @samp{/@var{user}@@@var{remote-host}:@var{path-on-remote-host}}. The
+ − 62 syntax for using ssh is
+ − 63 @samp{/[@var{user}@@@var{remote-host}]@var{path-on-remote-host}}.
+ − 64
+ − 65 In both cases the @samp{@var{user}@@} portion is optional (it defaults
+ − 66 to your local user name). @var{path-on-remote-host} may use the
+ − 67 @samp{~} notation to indicate @var{user}'s home directory on the remote
+ − 68 host. The default file name will reflect the remote host information.
+ − 69
428
+ − 70 @vindex default-directory
+ − 71 Each buffer has a default directory, normally the same as the
+ − 72 directory of the file visited in that buffer. When Emacs reads a file
+ − 73 name, the default directory is used if you do not specify a directory.
+ − 74 If you specify a directory in a relative fashion, with a name that does
+ − 75 not start with a slash, it is interpreted with respect to the default
+ − 76 directory. The default directory of the current buffer is kept in the
+ − 77 variable @code{default-directory}, which has a separate value in every
+ − 78 buffer. The value of the variable should end with a slash.
+ − 79
+ − 80 For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
+ − 81 the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo},
+ − 82 which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
+ − 83 @samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo}
+ − 84 would stand for the filename @file{/u/rms/gnu/new/foo}.
+ − 85
741
+ − 86 When visiting a remote file via EFS or TRAMP, the remote directory
+ − 87 becomes the default directory (@pxref{Visiting}) for that buffer, just
+ − 88 as a local directory would.
+ − 89
428
+ − 90 @vindex default-directory-alist
+ − 91 The variable @code{default-directory-alist} takes an alist of major
+ − 92 modes and their opinions on @code{default-directory} as a Lisp
+ − 93 expression to evaluate. A resulting value of @code{nil} is ignored in
+ − 94 favor of @code{default-directory}.
+ − 95
+ − 96 @findex make-directory
+ − 97 @findex remove-directory
+ − 98 @cindex creating directories
+ − 99 @cindex removing directories
+ − 100 You can create a new directory with the function @code{make-directory},
+ − 101 which takes as an argument a file name string. The current directory is
+ − 102 displayed in the minibuffer when the function is called; you can delete
+ − 103 the old directory name and supply a new directory name. For example, if
+ − 104 the current directory is @file{/u/rms/gnu}, you can delete @file{gnu}
+ − 105 and type @file{oryx} and @key{RET} to create @file{/u/rms/oryx}.
+ − 106 Removing a directory is similar to creating one. To remove a directory,
+ − 107 use @code{remove-directory}; it takes one argument, a file name string.
+ − 108
+ − 109 The command @kbd{M-x pwd} prints the current buffer's default directory,
+ − 110 and the command @kbd{M-x cd} sets it (to a value read using the
+ − 111 minibuffer). A buffer's default directory changes only when the @code{cd}
+ − 112 command is used. A file-visiting buffer's default directory is initialized
+ − 113 to the directory of the file that is visited there. If a buffer is created
+ − 114 with @kbd{C-x b}, its default directory is copied from that of the
+ − 115 buffer that was current at the time.
+ − 116
+ − 117 @vindex insert-default-directory
+ − 118 The default directory name actually appears in the minibuffer when the
+ − 119 minibuffer becomes active to read a file name. This serves two
+ − 120 purposes: it shows you what the default is, so that you can type a
+ − 121 relative file name and know with certainty what it will mean, and it
+ − 122 allows you to edit the default to specify a different directory. To
+ − 123 inhibit the insertion of the default directory, set the variable
+ − 124 @code{insert-default-directory} to @code{nil}.
+ − 125
+ − 126 Note that it is legitimate to type an absolute file name after you
+ − 127 enter the minibuffer, ignoring the presence of the default directory
+ − 128 name. The final minibuffer contents may look invalid, but that is not
+ − 129 so. @xref{Minibuffer File}.
+ − 130
+ − 131 @samp{$} in a file name is used to substitute environment variables. For
+ − 132 example, if you have used the shell command @samp{setenv FOO rms/hacks} to
+ − 133 set up an environment variable named @samp{FOO}, then you can use
+ − 134 @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an abbreviation for
+ − 135 @file{/u/rms/hacks/test.c}. The environment variable name consists of all
+ − 136 the alphanumeric characters after the @samp{$}; alternatively, it may be
+ − 137 enclosed in braces after the @samp{$}. Note that the @samp{setenv} command
+ − 138 affects Emacs only if done before Emacs is started.
+ − 139
+ − 140 To access a file with @samp{$} in its name, type @samp{$$}. This pair
+ − 141 is converted to a single @samp{$} at the same time variable substitution
+ − 142 is performed for single @samp{$}. The Lisp function that performs the
+ − 143 substitution is called @code{substitute-in-file-name}. The substitution
+ − 144 is performed only on filenames read as such using the minibuffer.
+ − 145
+ − 146 @node Visiting, Saving, File Names, Files
+ − 147 @section Visiting Files
+ − 148 @cindex visiting files
+ − 149
+ − 150 @c WideCommands
+ − 151 @table @kbd
+ − 152 @item C-x C-f
+ − 153 Visit a file (@code{find-file}).
+ − 154 @item C-x C-v
+ − 155 Visit a different file instead of the one visited last
+ − 156 (@code{find-alternate-file}).
+ − 157 @item C-x 4 C-f
+ − 158 Visit a file, in another window (@code{find-file-other-window}). Don't
+ − 159 change this window.
+ − 160 @item C-x 5 C-f
+ − 161 Visit a file, in another frame (@code{find-file-other-frame}). Don't
+ − 162 change this window or frame.
+ − 163 @end table
+ − 164
+ − 165 @cindex files
+ − 166 @cindex visiting
+ − 167 @cindex saving
+ − 168 @dfn{Visiting} a file means copying its contents into an Emacs buffer
+ − 169 so you can edit it. Emacs creates a new buffer for each file you
+ − 170 visit. We say that the buffer is visiting the file that it was created
+ − 171 to hold. Emacs constructs the buffer name from the file name by
+ − 172 throwing away the directory and keeping just the file name. For example,
+ − 173 a file named @file{/usr/rms/emacs.tex} is displayed in a buffer named
+ − 174 @samp{emacs.tex}. If a buffer with that name exists, a unique
+ − 175 name is constructed by appending @samp{<2>}, @samp{<3>},and so on, using
+ − 176 the lowest number that makes a name that is not already in use.
+ − 177
+ − 178 Each window's mode line shows the name of the buffer that is being displayed
+ − 179 in that window, so you can always tell what buffer you are editing.
+ − 180
+ − 181 The changes you make with Emacs are made in the Emacs buffer. They do
+ − 182 not take effect in the file that you visit, or any other permanent
+ − 183 place, until you @dfn{save} the buffer. Saving the buffer means that
+ − 184 Emacs writes the current contents of the buffer into its visited file.
+ − 185 @xref{Saving}.
+ − 186
+ − 187 @cindex modified (buffer)
+ − 188 If a buffer contains changes that have not been saved, the buffer is said
+ − 189 to be @dfn{modified}. This is important because it implies that some
+ − 190 changes will be lost if the buffer is not saved. The mode line displays
+ − 191 two stars near the left margin if the buffer is modified.
+ − 192
+ − 193 @kindex C-x 5 C-f
+ − 194 @findex find-file
+ − 195 @findex find-file-other-frame
+ − 196 To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
+ − 197 the command with the name of the file you wish to visit, terminated by a
+ − 198 @key{RET}. If you are using XEmacs under X, you can also use the
+ − 199 @b{Open...} command from the @b{File} menu bar item.
+ − 200
+ − 201 The file name is read using the minibuffer (@pxref{Minibuffer}), with
+ − 202 defaulting and completion in the standard manner (@pxref{File Names}).
+ − 203 While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
+ − 204
+ − 205 @kbd{C-x C-f} has completed successfully when text appears on the
+ − 206 screen and a new buffer name appears in the mode line. If the specified
+ − 207 file does not exist and could not be created or cannot be read, an error
+ − 208 results. The error message is printed in the echo area, and includes
+ − 209 the name of the file that Emacs was trying to visit.
+ − 210
+ − 211 If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
+ − 212 another copy. It selects the existing buffer containing that file.
+ − 213 However, before doing so, it checks that the file itself has not changed
+ − 214 since you visited or saved it last. If the file has changed, Emacs
+ − 215 prints a warning message. @xref{Interlocking,,Simultaneous Editing}.
+ − 216
+ − 217 @findex find-this-file
+ − 218 You can switch to a specific file called out in the current buffer by
+ − 219 calling the function @code{find-this-file}. By providing a prefix
+ − 220 argument, this function calls @code{filename-at-point} and switches to a
+ − 221 buffer visiting the file @var{filename}. It creates one if none already
+ − 222 exists. You can use this function to edit the file mentioned in the
+ − 223 buffer you are working in or to test if the file exists. You can do that
+ − 224 by using the minibuffer completion after snatching the all or part of
+ − 225 the filename.
+ − 226
+ − 227 @vindex find-file-use-truenames
+ − 228 @vindex buffer-file-name
+ − 229 If the variable @code{find-file-use-truenames}'s value is
+ − 230 non-@code{nil}, a buffer's visited filename will always be traced back
+ − 231 to the real file. The filename will never be a symbolic link, and there
+ − 232 will never be a symbolic link anywhere in its directory path. In other
+ − 233 words, the @code{buffer-file-name} and @code{buffer-file-truename} will
+ − 234 be equal.
+ − 235
+ − 236 @vindex find-file-compare-truenames
+ − 237 @vindex buffer-file-truename
+ − 238 If the variable @code{find-file-compare-truenames} value is
+ − 239 non-@code{nil}, the @code{find-file} command will check the
+ − 240 @code{buffer-file-truename} of all visited files when deciding whether a
+ − 241 given file is already in a buffer, instead of just
+ − 242 @code{buffer-file-name}. If you attempt to visit another file which is
444
+ − 243 a symbolic link to a file that is already in a buffer, the existing
+ − 244 buffer will be found instead of a newly created one. This works if any
+ − 245 component of the pathname (including a non-terminal component) is a
+ − 246 symbolic link as well, but doesn't work with hard links (nothing does).
428
+ − 247
+ − 248 @cindex creating files
+ − 249 If you want to create a file, just visit it. Emacs prints
+ − 250 @samp{(New File)} in the echo area, but in other respects behaves as if you
+ − 251 had visited an existing empty file. If you make any changes and save them,
+ − 252 the file is created.
+ − 253
+ − 254 @kindex C-x C-v
+ − 255 @findex find-alternate-file
+ − 256 If you visit a nonexistent file unintentionally (because you typed the
+ − 257 wrong file name), use the @kbd{C-x C-v} (@code{find-alternate-file})
+ − 258 command to visit the file you wanted. @kbd{C-x C-v} is similar to @kbd{C-x
+ − 259 C-f}, but it kills the current buffer (after first offering to save it if
+ − 260 it is modified). @kbd{C-x C-v} is allowed even if the current buffer
+ − 261 is not visiting a file.
+ − 262
+ − 263 @vindex find-file-run-dired
+ − 264 If the file you specify is actually a directory, Dired is called on
+ − 265 that directory (@pxref{Dired}). To inhibit this, set the variable
+ − 266 @code{find-file-run-dired} to @code{nil}; then it is an error to try to
+ − 267 visit a directory.
+ − 268
+ − 269 @kindex C-x 4 f
+ − 270 @findex find-file-other-window
+ − 271 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
+ − 272 except that the buffer containing the specified file is selected in another
+ − 273 window. The window that was selected before @kbd{C-x 4 f} continues to
+ − 274 show the same buffer it was already showing. If you use this command when
+ − 275 only one window is being displayed, that window is split in two, with one
+ − 276 window showing the same buffer as before, and the other one showing the
+ − 277 newly requested file. @xref{Windows}.
+ − 278
+ − 279 @kindex C-x 5 C-f
+ − 280 @findex find-file-other-frame
+ − 281 @kbd{C-x 5 C-f} (@code{find-file-other-frame}) is like @kbd{C-x C-f}
+ − 282 except that it creates a new frame in which the file is displayed.
+ − 283
+ − 284 @findex find-this-file-other-window
+ − 285 Use the function @code{find-this-file-other-window} to edit a file
+ − 286 mentioned in the buffer you are editing or to test if that file exists.
+ − 287 To do this, use the minibuffer completion after snatching the part or
+ − 288 all of the filename. By providing a prefix argument, the function calls
+ − 289 @code{filename-at-point} and switches you to a buffer visiting the file
+ − 290 @var{filename} in another window. The function creates a buffer if none
+ − 291 already exists. This function is similar to @code{find-file-other-window}.
+ − 292
+ − 293 @vindex find-file-hooks
+ − 294 @vindex find-file-not-found-hooks
+ − 295 There are two hook variables that allow extensions to modify the
+ − 296 operation of visiting files. Visiting a file that does not exist runs the
+ − 297 functions in the list @code{find-file-not-found-hooks}; the value of this
+ − 298 variable is expected to be a list of functions which are
+ − 299 called one by one until one of them returns non-@code{nil}. Any visiting
+ − 300 of a file, whether extant or not, expects @code{find-file-hooks} to
+ − 301 contain list of functions and calls them all, one by one. In both cases
+ − 302 the functions receive no arguments. Visiting a nonexistent file
+ − 303 runs the @code{find-file-not-found-hooks} first.
+ − 304
+ − 305 @node Saving, Reverting, Visiting, Files
+ − 306 @section Saving Files
+ − 307
+ − 308 @dfn{Saving} a buffer in Emacs means writing its contents back into the file
+ − 309 that was visited in the buffer.
+ − 310
+ − 311 @table @kbd
+ − 312 @item C-x C-s
+ − 313 Save the current buffer in its visited file (@code{save-buffer}).
+ − 314 @item C-x s
+ − 315 Save any or all buffers in their visited files (@code{save-some-buffers}).
+ − 316 @item M-~
+ − 317 Forget that the current buffer has been changed (@code{not-modified}).
+ − 318 @item C-x C-w
+ − 319 Save the current buffer in a specified file, and record that file as
+ − 320 the one visited in the buffer (@code{write-file}).
+ − 321 @item M-x set-visited-file-name
+ − 322 Change file the name under which the current buffer will be saved.
+ − 323 @end table
+ − 324
+ − 325 @kindex C-x C-s
+ − 326 @findex save-buffer
+ − 327 To save a file and make your changes permanent, type
+ − 328 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
+ − 329 prints a message such as:
+ − 330
+ − 331 @example
+ − 332 Wrote /u/rms/gnu/gnu.tasks
+ − 333 @end example
+ − 334
+ − 335 @noindent
+ − 336 If the selected buffer is not modified (no changes have been made in it
+ − 337 since the buffer was created or last saved), Emacs does not save it
+ − 338 because it would have no effect. Instead, @kbd{C-x C-s} prints a message
+ − 339 in the echo area saying:
+ − 340
+ − 341 @example
+ − 342 (No changes need to be saved)
+ − 343 @end example
+ − 344
+ − 345 @kindex C-x s
+ − 346 @findex save-some-buffers
+ − 347 The command @kbd{C-x s} (@code{save-some-buffers}) can save any or all
+ − 348 modified buffers. First it asks, for each modified buffer, whether to
+ − 349 save it. The questions should be answered with @kbd{y} or @kbd{n}.
+ − 350 @kbd{C-x C-c}, the key that kills Emacs, invokes
+ − 351 @code{save-some-buffers} and therefore asks the same questions.
+ − 352
+ − 353 @kindex M-~
+ − 354 @findex not-modified
+ − 355 If you have changed a buffer and do not want the changes to be saved,
+ − 356 you should take some action to prevent it. Otherwise, you are liable to
+ − 357 save it by mistake each time you use @code{save-some-buffers} or a
+ − 358 related command. One thing you can do is type @kbd{M-~}
+ − 359 (@code{not-modified}), which removes the indication that the buffer
+ − 360 is modified. If you do this, none of the save commands will believe
+ − 361 that the buffer needs to be saved. (@samp{~} is often used as a
+ − 362 mathematical symbol for `not'; thus @kbd{Meta-~} is `not', metafied.)
+ − 363 You could also use @code{set-visited-file-name} (see below) to mark the
+ − 364 buffer as visiting a different file name, not in use for
+ − 365 anything important.
+ − 366
+ − 367 You can also undo all the changes made since the file was visited or
+ − 368 saved, by reading the text from the file again. This is called
+ − 369 @dfn{reverting}. @xref{Reverting}. Alternatively, you can undo all the
+ − 370 changes by repeating the undo command @kbd{C-x u}; but this only works
+ − 371 if you have not made more changes than the undo mechanism can remember.
+ − 372
+ − 373 @findex set-visited-file-name
+ − 374 @kbd{M-x set-visited-file-name} alters the name of the file that the
+ − 375 current buffer is visiting. It prompts you for the new file name in the
+ − 376 minibuffer. You can also use @code{set-visited-file-name} on a buffer
+ − 377 that is not visiting a file. The buffer's name is changed to correspond
+ − 378 to the file it is now visiting unless the new name is already used by a
+ − 379 different buffer; in that case, the buffer name is not changed.
+ − 380 @code{set-visited-file-name} does not save the buffer in the newly
+ − 381 visited file; it just alters the records inside Emacs so that it will
+ − 382 save the buffer in that file. It also marks the buffer as ``modified''
+ − 383 so that @kbd{C-x C-s} @i{will} save.
+ − 384
+ − 385 @kindex C-x C-w
+ − 386 @findex write-file
+ − 387 If you wish to mark a buffer as visiting a different file and save it
+ − 388 right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely
+ − 389 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
+ − 390 @kbd{C-x C-s} used on a buffer that is not visiting a file has the
+ − 391 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
+ − 392 buffer as visiting that file, and saves it there. The default file name in
+ − 393 a buffer that is not visiting a file is made by combining the buffer name
+ − 394 with the buffer's default directory.
+ − 395
+ − 396 If Emacs is about to save a file and sees that the date of the latest
+ − 397 version on disk does not match what Emacs last read or wrote, Emacs
+ − 398 notifies you of this fact, because it probably indicates a problem caused
+ − 399 by simultaneous editing and requires your immediate attention.
+ − 400 @xref{Interlocking,, Simultaneous Editing}.
+ − 401
+ − 402 @vindex require-final-newline
+ − 403 If the variable @code{require-final-newline} is non-@code{nil}, Emacs
+ − 404 puts a newline at the end of any file that doesn't already end in one,
+ − 405 every time a file is saved or written.
+ − 406
+ − 407 @vindex write-file-hooks
+ − 408 @vindex after-save-hook
+ − 409 Use the hook variable @code{write-file-hooks} to implement other ways
+ − 410 to write files, and specify things to be done before files are written. The
+ − 411 value of this variable should be a list of Lisp functions. When a file
+ − 412 is to be written, the functions in the list are called, one by one, with
+ − 413 no arguments. If one of them returns a non-@code{nil} value, Emacs
+ − 414 takes this to mean that the file has been written in some suitable
+ − 415 fashion; the rest of the functions are not called, and normal writing is
+ − 416 not done. Use the hook variable @code{after-save-hook} to list
+ − 417 all the functions to be called after writing out a buffer to a file.
+ − 418
+ − 419 @menu
+ − 420 * Backup:: How Emacs saves the old version of your file.
+ − 421 * Interlocking:: How Emacs protects against simultaneous editing
+ − 422 of one file by two users.
+ − 423 @end menu
+ − 424
+ − 425 @node Backup, Interlocking, Saving, Saving
+ − 426 @subsection Backup Files
+ − 427 @cindex backup file
+ − 428 @vindex make-backup-files
+ − 429
+ − 430 Because Unix does not provide version numbers in file names, rewriting a
+ − 431 file in Unix automatically destroys all record of what the file used to
+ − 432 contain. Thus, saving a file from Emacs throws away the old contents of
+ − 433 the file---or it would, except that Emacs carefully copies the old contents
+ − 434 to another file, called the @dfn{backup} file, before actually saving.
+ − 435 (Make sure that the variable @code{make-backup-files} is non-@code{nil}.
+ − 436 Backup files are not written if this variable is @code{nil}).
+ − 437
+ − 438 At your option, Emacs can keep either a single backup file or a series of
+ − 439 numbered backup files for each file you edit.
+ − 440
+ − 441 Emacs makes a backup for a file only the first time a file is saved
+ − 442 from one buffer. No matter how many times you save a file, its backup file
+ − 443 continues to contain the contents from before the file was visited.
+ − 444 Normally this means that the backup file contains the contents from before
+ − 445 the current editing session; however, if you kill the buffer and then visit
+ − 446 the file again, a new backup file is made by the next save.
+ − 447
+ − 448 @menu
+ − 449 * Names: Backup Names. How backup files are named;
+ − 450 Choosing single or numbered backup files.
+ − 451 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
+ − 452 * Copying: Backup Copying. Backups can be made by copying or renaming.
+ − 453 @end menu
+ − 454
+ − 455 @node Backup Names, Backup Deletion, Backup, Backup
+ − 456 @subsubsection Single or Numbered Backups
+ − 457
+ − 458 If you choose to have a single backup file (the default),
+ − 459 the backup file's name is constructed by appending @samp{~} to the
+ − 460 file name being edited; thus, the backup file for @file{eval.c} is
+ − 461 @file{eval.c~}.
+ − 462
+ − 463 If you choose to have a series of numbered backup files, backup file
+ − 464 names are made by appending @samp{.~}, the number, and another @samp{~} to
+ − 465 the original file name. Thus, the backup files of @file{eval.c} would be
+ − 466 called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
+ − 467 like @file{eval.c.~259~} and beyond.
+ − 468
+ − 469 If protection stops you from writing backup files under the usual names,
+ − 470 the backup file is written as @file{%backup%~} in your home directory.
+ − 471 Only one such file can exist, so only the most recently made backup is
+ − 472 available.
+ − 473
+ − 474 @vindex version-control
+ − 475 The choice of single backup or numbered backups is controlled by the
+ − 476 variable @code{version-control}. Its possible values are:
+ − 477
+ − 478 @table @code
+ − 479 @item t
+ − 480 Make numbered backups.
+ − 481 @item nil
+ − 482 Make numbered backups for files that have numbered backups already.
+ − 483 Otherwise, make single backups.
+ − 484 @item never
+ − 485 Never make numbered backups; always make single backups.
+ − 486 @end table
+ − 487
+ − 488 @noindent
+ − 489 @code{version-control} may be set locally in an individual buffer to
+ − 490 control the making of backups for that buffer's file. For example,
+ − 491 Rmail mode locally sets @code{version-control} to @code{never} to make sure
+ − 492 that there is only one backup for an Rmail file. @xref{Locals}.
+ − 493
+ − 494 @node Backup Deletion, Backup Copying, Backup Names, Backup
+ − 495 @subsubsection Automatic Deletion of Backups
+ − 496
+ − 497 @vindex kept-old-versions
+ − 498 @vindex kept-new-versions
+ − 499 To prevent unlimited consumption of disk space, Emacs can delete numbered
+ − 500 backup versions automatically. Generally Emacs keeps the first few backups
+ − 501 and the latest few backups, deleting any in between. This happens every
+ − 502 time a new backup is made. The two variables that control the deletion are
+ − 503 @code{kept-old-versions} and @code{kept-new-versions}. Their values are, respectively
+ − 504 the number of oldest (lowest-numbered) backups to keep and the number of
+ − 505 newest (highest-numbered) ones to keep, each time a new backup is made.
+ − 506 The values are used just after a new backup version is made;
+ − 507 that newly made backup is included in the count in @code{kept-new-versions}.
+ − 508 By default, both variables are 2.
+ − 509
442
+ − 510 @vindex delete-old-versions
+ − 511 If @code{delete-old-versions} is non-@code{nil}, excess
428
+ − 512 middle versions are deleted without notification. If it is @code{nil}, the
+ − 513 default, you are asked whether the excess middle versions should
+ − 514 really be deleted.
+ − 515
+ − 516 You can also use Dired's @kbd{.} (Period) command to delete old versions.
+ − 517 @xref{Dired}.
+ − 518
+ − 519 @node Backup Copying, , Backup Deletion, Backup
+ − 520 @subsubsection Copying vs.@: Renaming
+ − 521
+ − 522 You can make backup files by copying the old file or by renaming it.
+ − 523 This makes a difference when the old file has multiple names. If you
+ − 524 rename the old file into the backup file, the alternate names
+ − 525 become names for the backup file. If you copy the old file instead,
+ − 526 the alternate names remain names for the file that you are editing,
+ − 527 and the contents accessed by those names will be the new contents.
+ − 528
+ − 529 How you make a backup file may also affect the file's owner
+ − 530 and group. If you use copying, they do not change. If renaming is used,
+ − 531 you become the file's owner, and the file's group becomes the default
+ − 532 (different operating systems have different defaults for the group).
+ − 533
+ − 534 Having the owner change is usually a good idea, because then the owner
+ − 535 is always the person who last edited the file. Occasionally there is a
+ − 536 file whose owner should not change. Since most files should change
+ − 537 owners, it is a good idea to use local variable lists to set
+ − 538 @code{backup-by-copying-when-mismatch} for the special cases where the
+ − 539 owner should not change (@pxref{File Variables}).
+ − 540
+ − 541 @vindex backup-by-copying
+ − 542 @vindex backup-by-copying-when-linked
+ − 543 @vindex backup-by-copying-when-mismatch
+ − 544 Three variables control the choice of renaming or copying.
+ − 545 Normally, renaming is done. If the variable @code{backup-by-copying} is
+ − 546 non-@code{nil}, copying is used. Otherwise, if the variable
+ − 547 @code{backup-by-copying-when-linked} is non-@code{nil}, copying is
+ − 548 done for files that have multiple names, but renaming may still be done when
+ − 549 the file being edited has only one name. If the variable
+ − 550 @code{backup-by-copying-when-mismatch} is non-@code{nil}, copying is
+ − 551 done if renaming would cause the file's owner or group to change. @refill
+ − 552
+ − 553 @node Interlocking, , Backup, Saving
+ − 554 @subsection Protection Against Simultaneous Editing
+ − 555
+ − 556 @cindex file dates
+ − 557 @cindex simultaneous editing
+ − 558 Simultaneous editing occurs when two users visit the same file, both
+ − 559 make changes, and both save their changes. If no one was informed that
+ − 560 this was happening, and you saved first, you would later find that your
+ − 561 changes were lost. On some systems, Emacs notices immediately when the
+ − 562 second user starts to change a file already being edited, and issues a
+ − 563 warning. When this is not possible, or if the second user has started
+ − 564 to change the file despite the warning, Emacs checks when the file is
+ − 565 saved, and issues a second warning when a user is about to overwrite a
+ − 566 file containing another user's changes. If you are the user editing the
+ − 567 file, you can take corrective action at this point and prevent actual
+ − 568 loss of work.
+ − 569
+ − 570 @findex ask-user-about-lock
+ − 571 When you make the first modification in an Emacs buffer that is visiting
+ − 572 a file, Emacs records that you have locked the file. (It does this by
+ − 573 writing another file in a directory reserved for this purpose.) The lock
+ − 574 is removed when you save the changes. The idea is that the file is locked
+ − 575 whenever the buffer is modified. If you begin to modify the buffer while
+ − 576 the visited file is locked by someone else, this constitutes a collision,
+ − 577 and Emacs asks you what to do. It does this by calling the Lisp function
+ − 578 @code{ask-user-about-lock}, which you can redefine to customize what it
+ − 579 does. The standard definition of this function asks you a
+ − 580 question and accepts three possible answers:
+ − 581
+ − 582 @table @kbd
+ − 583 @item s
+ − 584 Steal the lock. Whoever was already changing the file loses the lock,
+ − 585 and you get the lock.
+ − 586 @item p
+ − 587 Proceed. Go ahead and edit the file despite its being locked by someone else.
+ − 588 @item q
+ − 589 Quit. This causes an error (@code{file-locked}) and the modification you
+ − 590 were trying to make in the buffer does not actually take place.
+ − 591 @end table
+ − 592
+ − 593 Note that locking works on the basis of a file name; if a file has
+ − 594 multiple names, Emacs does not realize that the two names are the same file
+ − 595 and cannot prevent two users from editing it simultaneously under different
+ − 596 names. However, basing locking on names means that Emacs can interlock the
+ − 597 editing of new files that do not really exist until they are saved.
+ − 598
+ − 599 Some systems are not configured to allow Emacs to make locks. On
+ − 600 these systems, Emacs cannot detect trouble in advance, but it can still
+ − 601 detect it in time to prevent you from overwriting someone else's changes.
+ − 602
+ − 603 Every time Emacs saves a buffer, it first checks the last-modification
+ − 604 date of the existing file on disk to see that it has not changed since the
+ − 605 file was last visited or saved. If the date does not match, it implies
+ − 606 that changes were made in the file in some other way, and these changes are
+ − 607 about to be lost if Emacs actually does save. To prevent this, Emacs
+ − 608 prints a warning message and asks for confirmation before saving.
+ − 609 Occasionally you will know why the file was changed and know that it does
+ − 610 not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should
+ − 611 cancel the save with @kbd{C-g} and investigate the situation.
+ − 612
+ − 613 The first thing you should do when notified that simultaneous editing
+ − 614 has already taken place is to list the directory with @kbd{C-u C-x C-d}
+ − 615 (@pxref{ListDir,,Directory Listing}). This will show the file's current
+ − 616 author. You should attempt to contact that person and ask him not to
+ − 617 continue editing. Often the next step is to save the contents of your
+ − 618 Emacs buffer under a different name, and use @code{diff} to compare the
+ − 619 two files.@refill
+ − 620
+ − 621 Simultaneous editing checks are also made when you visit a file that
+ − 622 is already visited with @kbd{C-x C-f} and when you start to modify a
+ − 623 file. This is not strictly necessary, but it is useful to find out
+ − 624 about such a problem as early as possible, when corrective action takes
+ − 625 less work.
+ − 626
+ − 627 @findex set-default-file-modes
+ − 628 @cindex file protection
+ − 629 Another way to protect your file is to set the read, write, and
+ − 630 executable permissions for the file. Use the function
+ − 631 @code{set-default-file-modes} to set the UNIX @code{umask} value to the
+ − 632 @var{nmask} argument. The @code{umask} value is the default protection
+ − 633 mode for new files.
+ − 634
+ − 635 @node Reverting, Auto Save, Saving, Files
+ − 636 @section Reverting a Buffer
+ − 637 @findex revert-buffer
+ − 638 @cindex drastic changes
+ − 639
+ − 640 If you have made extensive changes to a file and then change your mind
+ − 641 about them, you can get rid of all changes by reading in the previous
+ − 642 version of the file. To do this, use @kbd{M-x revert-buffer}, which
+ − 643 operates on the current buffer. Since reverting a buffer can result in
+ − 644 very extensive changes, you must confirm it with @kbd{yes}.
+ − 645
+ − 646 If the current buffer has been auto-saved more recently than it has been
+ − 647 saved explicitly, @code{revert-buffer} offers to read the auto save file
+ − 648 instead of the visited file (@pxref{Auto Save}). Emacs asks you about
+ − 649 the auto-save file before the request for confirmation of the
+ − 650 @kbd{revert-buffer} operation, and demands @kbd{y} or @kbd{n}
+ − 651 as an answer. If you have started to type @kbd{yes} for confirmation
+ − 652 without realizing that the auto-save question was going to be asked, the
+ − 653 @kbd{y} will answer that question, but the @kbd{es} will not be valid
+ − 654 confirmation. This gives you a chance to cancel the operation with
+ − 655 @kbd{C-g} and try again with the answers you really intend.
+ − 656
+ − 657 @code{revert-buffer} keeps point at the same distance (measured in
+ − 658 characters) from the beginning of the file. If the file was edited only
+ − 659 slightly, you will be at approximately the same piece of text after
+ − 660 reverting as before. If you have made more extensive changes, the value of
+ − 661 point in the old file may bring you to a totally different piece of text
+ − 662 than your last editing point.
+ − 663
+ − 664 A buffer reverted from its visited file is marked ``not modified'' until
+ − 665 you make a change.
+ − 666
+ − 667 Some kinds of buffers whose contents reflect data bases other than files,
+ − 668 such as Dired buffers, can also be reverted. For them, reverting means
+ − 669 recalculating their contents from the appropriate data. Buffers
+ − 670 created randomly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
+ − 671 reports an error when asked to do so.
+ − 672
+ − 673 @node Auto Save, Version Control, Reverting, Files
+ − 674 @section Auto-Saving: Protection Against Disasters
+ − 675 @cindex Auto-Save mode
+ − 676 @cindex crashes
+ − 677
+ − 678 Emacs saves all the visited files from time to time (based on counting
+ − 679 your keystrokes) without being asked. This is called @dfn{auto-saving}.
+ − 680 It prevents you from losing more than a limited amount of work if the
+ − 681 system crashes.
+ − 682
+ − 683 When Emacs determines it is time for auto-saving, each buffer is
+ − 684 considered and is auto-saved if auto-saving is turned on for it and it has
+ − 685 changed since the last time it was auto-saved. If any auto-saving is
+ − 686 done, the message @samp{Auto-saving...} is displayed in the echo area until
+ − 687 auto-saving is finished. Errors occurring during auto-saving are caught
+ − 688 so that they do not interfere with the execution of commands you have been
+ − 689 typing.
+ − 690
+ − 691 @menu
+ − 692 * Files: Auto Save Files.
+ − 693 * Control: Auto Save Control.
+ − 694 * Recover:: Recovering text from auto-save files.
+ − 695 @end menu
+ − 696
+ − 697 @node Auto Save Files, Auto Save Control, Auto Save, Auto Save
+ − 698 @subsection Auto-Save Files
+ − 699
+ − 700 Auto-saving does not normally write to the files you visited, because
+ − 701 it can be undesirable to save a program that is in an inconsistent
+ − 702 state when you have made only half of a planned change. Instead, auto-saving
+ − 703 is done in a different file called the @dfn{auto-save file}, and the
+ − 704 visited file is changed only when you save explicitly, for example,
+ − 705 with @kbd{C-x C-s}.
+ − 706
+ − 707 Normally, the name of the auto-save file is generated by appending
+ − 708 @samp{#} to the front and back of the visited file name. Thus, a buffer
+ − 709 visiting file @file{foo.c} would be auto-saved in a file @file{#foo.c#}.
+ − 710 Most buffers that are not visiting files are auto-saved only if you
+ − 711 request it explicitly; when they are auto-saved, the auto-save file name
+ − 712 is generated by appending @samp{#%} to the front and @samp{#} to the
+ − 713 back of buffer name. For example, the @samp{*mail*} buffer in which you
+ − 714 compose messages to be sent is auto-saved in a file named
+ − 715 @file{#%*mail*#}. Names of auto-save files are generated this way
+ − 716 unless you customize the functions @code{make-auto-save-file-name} and
+ − 717 @code{auto-save-file-name-p} to do something different. The file name
+ − 718 to be used for auto-saving a buffer is calculated at the time auto-saving is
+ − 719 turned on in that buffer.
+ − 720
+ − 721 @vindex auto-save-visited-file-name
+ − 722 If you want auto-saving to be done in the visited file, set the variable
+ − 723 @code{auto-save-visited-file-name} to be non-@code{nil}. In this mode,
+ − 724 there is really no difference between auto-saving and explicit saving.
+ − 725
+ − 726 @vindex delete-auto-save-files
+ − 727 Emacs deletes a buffer's auto-save file when you explicitly save the
+ − 728 buffer. To inhibit the deletion, set the variable
+ − 729 @code{delete-auto-save-files} to @code{nil}. Changing the visited file
+ − 730 name with @kbd{C-x C-w} or @code{set-visited-file-name} renames any
+ − 731 auto-save file to correspond to the new visited name.
+ − 732
+ − 733 @node Auto Save Control, Recover, Auto Save Files, Auto Save
+ − 734 @subsection Controlling Auto-Saving
+ − 735
+ − 736 @vindex auto-save-default
+ − 737 @findex auto-save-mode
+ − 738 Each time you visit a file, auto-saving is turned on for that file's
+ − 739 buffer if the variable @code{auto-save-default} is non-@code{nil} (but
+ − 740 not in batch mode; @pxref{Entering Emacs}). The default for this
+ − 741 variable is @code{t}, so Emacs auto-saves buffers that visit files by
+ − 742 default. You can use the command @kbd{M-x auto-save-mode} to turn
+ − 743 auto-saving for a buffer on or off. Like other minor mode commands,
+ − 744 @kbd{M-x auto-save-mode} turns auto-saving on with a positive argument,
+ − 745 off with a zero or negative argument; with no argument, it toggles.
+ − 746
+ − 747 @vindex auto-save-interval
+ − 748 @findex do-auto-save
+ − 749 Emacs performs auto-saving periodically based on counting how many
+ − 750 characters you have typed since the last time auto-saving happened. The
+ − 751 variable @code{auto-save-interval} specifies the number of characters
+ − 752 between auto-saves. By default, it is 300. Emacs also auto-saves
+ − 753 whenever you call the function @code{do-auto-save}.
+ − 754
+ − 755 Emacs also does auto-saving whenever it gets a fatal error. This
+ − 756 includes killing the Emacs job with a shell command such as @code{kill
+ − 757 -emacs}, or disconnecting a phone line or network connection.
+ − 758
+ − 759 @vindex auto-save-timeout
+ − 760 You can set the number of seconds of idle time before an auto-save is
+ − 761 done. Setting the value of the variable @code{auto-save-timeout} to zero or
+ − 762 @code{nil} will disable auto-saving due to idleness.
+ − 763
+ − 764 The actual amount of idle time between auto-saves is logarithmically
+ − 765 related to the size of the current buffer. This variable is the number
+ − 766 of seconds after which an auto-save will happen when the current buffer
+ − 767 is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3
+ − 768 3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k
+ − 769 buffer.
+ − 770
+ − 771 For this variable to have any effect, you must do @code{(require 'timer)}.
+ − 772
+ − 773 @node Recover, , Auto Save Control, Auto Save
+ − 774 @subsection Recovering Data from Auto-Saves
+ − 775
+ − 776 @findex recover-file
+ − 777 If you want to use the contents of an auto-save file to recover from a
+ − 778 loss of data, use the command @kbd{M-x recover-file @key{RET} @var{file}
+ − 779 @key{RET}}. Emacs visits @var{file} and then (after your confirmation)
+ − 780 restores the contents from the auto-save file @file{#@var{file}#}. You
+ − 781 can then save the file with @kbd{C-x C-s} to put the recovered text into
+ − 782 @var{file} itself. For example, to recover file @file{foo.c} from its
+ − 783 auto-save file @file{#foo.c#}, do:@refill
+ − 784
+ − 785 @example
+ − 786 M-x recover-file @key{RET} foo.c @key{RET}
+ − 787 C-x C-s
+ − 788 @end example
+ − 789
+ − 790 Before asking for confirmation, @kbd{M-x recover-file} displays a
+ − 791 directory listing describing the specified file and the auto-save file,
+ − 792 so you can compare their sizes and dates. If the auto-save file
+ − 793 is older, @kbd{M-x recover-file} does not offer to read it.
+ − 794
+ − 795 Auto-saving is disabled by @kbd{M-x recover-file} because using
+ − 796 this command implies that the auto-save file contains valuable data
+ − 797 from a past session. If you save the data in the visited file and
+ − 798 then go on to make new changes, turn auto-saving back on
+ − 799 with @kbd{M-x auto-save-mode}.
+ − 800
+ − 801 @node Version Control, ListDir, Auto Save, Files
+ − 802 @section Version Control
+ − 803 @cindex version control
+ − 804
+ − 805 @dfn{Version control systems} are packages that can record multiple
+ − 806 versions of a source file, usually storing the unchanged parts of the
+ − 807 file just once. Version control systems also record history information
+ − 808 such as the creation time of each version, who created it, and a
+ − 809 description of what was changed in that version.
+ − 810
+ − 811 The GNU project recommends the version control system known as RCS,
+ − 812 which is free software and available from the Free Software Foundation.
+ − 813 Emacs supports use of either RCS or SCCS (a proprietary, but widely
+ − 814 used, version control system that is not quite as powerful as RCS)
+ − 815 through a facility called VC. The same Emacs commands work with either
+ − 816 RCS or SCCS, so you hardly have to know which one of them you are
+ − 817 using.
+ − 818
+ − 819 @menu
+ − 820 * Concepts of VC:: Basic version control information;
+ − 821 checking files in and out.
+ − 822 * Editing with VC:: Commands for editing a file maintained
+ − 823 with version control.
+ − 824 * Variables for Check-in/out:: Variables that affect the commands used
+ − 825 to check files in or out.
+ − 826 * Log Entries:: Logging your changes.
+ − 827 * Change Logs and VC:: Generating a change log file from log
+ − 828 entries.
+ − 829 * Old Versions:: Examining and comparing old versions.
+ − 830 * VC Status:: Commands to view the VC status of files and
+ − 831 look at log entries.
+ − 832 * Renaming and VC:: A command to rename both the source and
+ − 833 master file correctly.
+ − 834 * Snapshots:: How to make and use snapshots, a set of
+ − 835 file versions that can be treated as a unit.
+ − 836 * Version Headers:: Inserting version control headers into
+ − 837 working files.
+ − 838 @end menu
+ − 839
+ − 840 @node Concepts of VC, Editing with VC, Version Control, Version Control
+ − 841 @subsection Concepts of Version Control
+ − 842
+ − 843 @cindex RCS
+ − 844 @cindex SCCS
+ − 845 @cindex master file
+ − 846 @cindex registered file
+ − 847 @cindex work file
+ − 848 When a file is under version control, we also say that it is
+ − 849 @dfn{registered} in the version control system. Each registered file
+ − 850 has a corresponding @dfn{master file} which represents the file's
+ − 851 present state plus its change history, so that you can reconstruct from
+ − 852 it either the current version or any specified earlier version. Usually
+ − 853 the master file also records a @dfn{log entry} for each version describing
+ − 854 what was changed in that version.
+ − 855
+ − 856 The file that is maintained under version control is sometimes called
+ − 857 the @dfn{work file} corresponding to its master file.
+ − 858
+ − 859 @cindex checking out files
+ − 860 @cindex checking in files
+ − 861 @cindex locking and version control
+ − 862 To examine a file, you @dfn{check it out}. This extracts a version
+ − 863 of the source file (typically, the most recent) from the master file.
+ − 864 If you want to edit the file, you must check it out @dfn{locked}. Only
+ − 865 one user can do this at a time for any given source file. (This kind
+ − 866 of locking is completely unrelated to the locking that Emacs uses to
+ − 867 detect simultaneous editing of a file.)
+ − 868
+ − 869 When you are done with your editing, you must @dfn{check in} the new
+ − 870 version. This records the new version in the master file, and unlocks
+ − 871 the source file so that other people can lock it and thus modify it.
+ − 872
+ − 873 Checkin and checkout are the basic operations of version control. You
+ − 874 can do both of them with a single Emacs command: @w{@kbd{C-x C-q}}
+ − 875 (@code{vc-toggle-read-only}).
+ − 876
+ − 877 A @dfn{snapshot} is a coherent collection of versions of the various
+ − 878 files that make up a program. @xref{Snapshots}.
+ − 879
+ − 880 @node Editing with VC, Variables for Check-in/out, Concepts of VC, Version Control
+ − 881 @subsection Editing with Version Control
+ − 882
+ − 883 When you visit a file that is maintained using version control, the
+ − 884 mode line displays @samp{RCS} or @samp{SCCS} to inform you that version
+ − 885 control is in use, and also (in case you care) which low-level system
+ − 886 the file is actually stored in. Normally, such a source file is
+ − 887 read-only, and the mode line indicates this with @samp{%%}. With RCS,
+ − 888 the mode line also indicates the number of the head version, which is
+ − 889 normally also the version you are looking at.
+ − 890
+ − 891 These are the commands for editing a file maintained with
+ − 892 version control:
+ − 893
+ − 894 @table @kbd
+ − 895 @item C-x C-q
+ − 896 Check the visited file in or out.
+ − 897
+ − 898 @item C-x v u
+ − 899 Revert the buffer and the file to the last checked in version.
+ − 900
+ − 901 @item C-x v c
+ − 902 Remove the last-entered change from the master for the visited file.
+ − 903 This undoes your last check-in.
+ − 904
+ − 905 @item C-x v i
+ − 906 Register the visited file in version control.
+ − 907 @end table
+ − 908
+ − 909 @noindent
+ − 910 (@kbd{C-x v} is the prefix key for version control commands; all of these
+ − 911 commands except for @kbd{C-x C-q} start with @kbd{C-x v}.)
+ − 912
+ − 913 @kindex C-x C-q @r{(version control)}
+ − 914 When you want to modify a file maintained with version control, type
+ − 915 @kbd{C-x C-q} (@code{vc-toggle-read-only}). This @dfn{checks out} the
+ − 916 file, and tells RCS or SCCS to lock the file. This means making the
+ − 917 file writable for you (but not for anyone else).
+ − 918
+ − 919 @cindex log entry
+ − 920 When you are finished editing the file, type @kbd{C-x C-q} again.
+ − 921 When used on a file that is checked out, this command checks the file
+ − 922 in. But check-in does not start immediately; first, you must enter the
+ − 923 @dfn{log entry}---a description of the changes in the new version.
+ − 924 @kbd{C-x C-q} pops up a buffer for you to enter this in. When you are
+ − 925 finished typing in the log entry, type @kbd{C-c C-c} to terminate it; this is
+ − 926 when actual check-in takes place.
+ − 927
+ − 928 Once you have checked in your changes, the file is unlocked, so that
+ − 929 other users can lock it and modify it.
+ − 930
+ − 931 @vindex vc-make-backup-files
+ − 932 Emacs does not save backup files for source files that are maintained
+ − 933 with version control. If you want to make backup files despite version
+ − 934 control, set the variable @code{vc-make-backup-files} to a
+ − 935 non-@code{nil} value.
+ − 936
+ − 937 @vindex vc-keep-workfiles
+ − 938 Normally the work file exists all the time, whether it is locked or
+ − 939 not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking
+ − 940 in a new version with @kbd{C-x C-q} deletes the work file; but any
+ − 941 attempt to visit the file with Emacs creates it again.
+ − 942
+ − 943 It is not impossible to lock a file that someone else has locked. If
+ − 944 you try to check out a file that is locked, @kbd{C-x C-q} asks you
+ − 945 whether you want to ``steal the lock.'' If you say yes, the file
+ − 946 becomes locked by you, but a message is sent to the person who had
+ − 947 formerly locked the file, to inform him of what has happened. The mode
+ − 948 line indicates that a file is locked by someone else by displaying the
+ − 949 login name of that person, before the version number.
+ − 950
+ − 951 @kindex C-x v u
+ − 952 @findex vc-revert-buffer
+ − 953 If you want to discard your current set of changes and revert to the
+ − 954 last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}).
+ − 955 This cancels your last check-out, leaving the file unlocked. If you want
+ − 956 to make a different set of changes, you must first check the file out
+ − 957 again. @kbd{C-x v u} requires confirmation, unless it sees that
+ − 958 you haven't made any changes since the last checked-in version.
+ − 959
+ − 960 @kbd{C-x v u} is also the command to use if you lock a file and then
+ − 961 don't actually change it.
+ − 962
+ − 963 @kindex C-x v c
+ − 964 @findex vc-cancel-version
+ − 965 You can cancel a change after checking it in, with @kbd{C-x v c}
+ − 966 (@code{vc-cancel-version}). This command discards all record of the
+ − 967 most recent checked in version, so be careful about using it. It
+ − 968 requires confirmation with @kbd{yes}. By default, @kbd{C-x v c} reverts
+ − 969 your workfile and buffer to the previous version (the one that precedes
+ − 970 the version that is deleted), but you can prevent the reversion by
+ − 971 giving the command a prefix argument. Then the buffer does not change.
+ − 972
+ − 973 This command with a prefix argument is useful when you have checked in
+ − 974 a change and then discover a trivial error in it; you can cancel the
+ − 975 erroneous check-in, fix the error, and repeat the check-in.
+ − 976
+ − 977 Be careful when invoking @kbd{C-x v c}, as it is easy to throw away a
+ − 978 lot of work with it. To help you be careful, this command always
+ − 979 requires confirmation with @samp{yes}.
+ − 980
+ − 981 @kindex C-x v i
+ − 982 @findex vc-register
+ − 983 @vindex vc-default-back-end
+ − 984 You can register the visited file for version control using
+ − 985 @w{@kbd{C-x v i}} (@code{vc-register}). If the variable
+ − 986 @code{vc-default-back-end} is non-@code{nil}, it specifies which
+ − 987 version control system to use; otherwise, this uses RCS if it is
+ − 988 installed on your system and SCCS if not. After @kbd{C-x v i},
+ − 989 the file is unlocked and read-only. Type @kbd{C-x C-q} if you wish to
+ − 990 edit it.
+ − 991
+ − 992 By default, the initial version number is 1.1. If you want to use a
+ − 993 different number, give @kbd{C-x v i} a prefix argument; then it reads
+ − 994 the initial version number using the minibuffer.
+ − 995
+ − 996 @vindex vc-initial-comment
+ − 997 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads
+ − 998 an initial comment (much like a log entry) to describe the purpose of
+ − 999 this source file.
+ − 1000
+ − 1001 @kindex C-u C-x v v
+ − 1002 @findex vc-next-action
+ − 1003 To specify the version number for a subsequent checkin, use the
+ − 1004 command @kbd{C-u C-x v v}. @kbd{C-x v v} (@code{vc-next-action}) is the
+ − 1005 command that @kbd{C-x C-q} uses to do the ``real work'' when the visited
+ − 1006 file uses version control. When used for checkin, and given a prefix
+ − 1007 argument, it reads the version number with the minibuffer.
+ − 1008
+ − 1009 @node Variables for Check-in/out, Log Entries, Editing with VC, Version Control
+ − 1010 @subsection Variables Affecting Check-in and Check-out
+ − 1011 @c There is no need to tell users about vc-master-templates.
+ − 1012
+ − 1013 @vindex vc-suppress-confirm
+ − 1014 If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q}
+ − 1015 and @kbd{C-x v i} can save the current buffer without asking, and
+ − 1016 @kbd{C-x v u} also operates without asking for confirmation.
+ − 1017 (This variable does not affect @kbd{C-x v c}; that is so drastic
+ − 1018 that it should always ask for confirmation.)
+ − 1019
+ − 1020 @vindex vc-command-messages
+ − 1021 VC mode does much of its work by running the shell commands for RCS
+ − 1022 and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC displays
+ − 1023 messages to indicate which shell commands it runs, and additional
+ − 1024 messages when the commands finish.
+ − 1025
+ − 1026 Normally, VC assumes that it can deduce the locked/unlocked state of
+ − 1027 files by looking at the file permissions of the work file; this is
+ − 1028 fast. However, if the @file{RCS} or @file{SCCS} subdirectory is
+ − 1029 actually a symbolic link, then VC does not trust the file permissions to
+ − 1030 reflect this status.
+ − 1031
+ − 1032 @vindex vc-mistrust-permissions
+ − 1033 You can specify the criterion for whether to trust the file permissions
+ − 1034 by setting the variable @code{vc-mistrust-permissions}. Its value may
+ − 1035 be @code{t} (always mistrust the file permissions and check the master
+ − 1036 file), @code{nil} (always trust the file permissions), or a function of
+ − 1037 one argument which makes the decision. The argument is the directory
+ − 1038 name of the @file{RCS} or @file{SCCS} subdirectory. A non-@code{nil}
+ − 1039 value from the function says to mistrust the file permissions.
+ − 1040
+ − 1041 If you find that the file permissions of work files are changed
+ − 1042 erroneously, set @code{vc-mistrust-permissions} to @code{t}. Then VC
+ − 1043 always checks the master file to determine the file's status.
+ − 1044
+ − 1045 @vindex vc-path
+ − 1046 You can specify additional directories to search for version control
+ − 1047 programs by setting the variable @code{vc-path}. These directories
+ − 1048 are searched before the usual search path. The proper result usually
+ − 1049 happens automatically.
+ − 1050
+ − 1051 @node Log Entries, Change Logs and VC, Variables for Check-in/out, Version Control
+ − 1052 @subsection Log Entries
+ − 1053
+ − 1054 When you're editing an initial comment or log entry for inclusion in a
+ − 1055 master file, finish your entry by typing @kbd{C-c C-c}.
+ − 1056
+ − 1057 @table @kbd
+ − 1058 @item C-c C-c
+ − 1059 Finish the comment edit normally (@code{vc-finish-logentry}).
+ − 1060 This finishes check-in.
+ − 1061 @end table
+ − 1062
+ − 1063 To abort check-in, just don't type @kbd{C-c C-c} in that buffer. You
+ − 1064 can switch buffers and do other editing. As long as you don't try to
+ − 1065 check in another file, the entry you were editing remains in its
+ − 1066 buffer, and you can go back to that buffer at any time to complete the
+ − 1067 check-in.
+ − 1068
+ − 1069 If you change several source files for the same reason, it is often
+ − 1070 convenient to specify the same log entry for many of the files. To do
+ − 1071 this, use the history of previous log entries. The commands @kbd{M-n},
+ − 1072 @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the
+ − 1073 minibuffer history commands (except that these versions are used outside
+ − 1074 the minibuffer).
+ − 1075
+ − 1076 @vindex vc-log-mode-hook
+ − 1077 Each time you check in a file, the log entry buffer is put into VC Log
+ − 1078 mode, which involves running two hooks: @code{text-mode-hook} and
+ − 1079 @code{vc-log-mode-hook}.
+ − 1080
+ − 1081 @node Change Logs and VC, Old Versions, Log Entries, Version Control
+ − 1082 @subsection Change Logs and VC
+ − 1083
+ − 1084 If you use RCS for a program and also maintain a change log file for
+ − 1085 it (@pxref{Change Log}), you can generate change log entries
+ − 1086 automatically from the version control log entries:
+ − 1087
+ − 1088 @table @kbd
+ − 1089 @item C-x v a
+ − 1090 @kindex C-x v a
+ − 1091 @findex vc-update-change-log
+ − 1092 Visit the current directory's change log file and create new entries for
+ − 1093 versions checked in since the most recent entry in the change log file
+ − 1094 (@code{vc-update-change-log}).
+ − 1095
+ − 1096 This command works with RCS only; it does not work with SCCS.
+ − 1097 @end table
+ − 1098
+ − 1099 For example, suppose the first line of @file{ChangeLog} is dated 10
+ − 1100 April 1992, and that the only check-in since then was by Nathaniel
+ − 1101 Bowditch to @file{rcs2log} on 8 May 1992 with log text @samp{Ignore log
+ − 1102 messages that start with `#'.}. Then @kbd{C-x v a} visits
+ − 1103 @file{ChangeLog} and inserts text like this:
+ − 1104
+ − 1105 @smallexample
+ − 1106 @group
+ − 1107 Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@@apn.org)
+ − 1108
+ − 1109 * rcs2log: Ignore log messages that start with `#'.
+ − 1110 @end group
+ − 1111 @end smallexample
+ − 1112
+ − 1113 @noindent
+ − 1114 You can then edit the new change log entry further as you wish.
+ − 1115
+ − 1116 Normally, the log entry for file @file{foo} is displayed as @samp{*
+ − 1117 foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted
+ − 1118 if the text of the log entry starts with @w{@samp{(@var{functionname}):
+ − 1119 }}. For example, if the log entry for @file{vc.el} is
+ − 1120 @samp{(vc-do-command): Check call-process status.}, then the text in
+ − 1121 @file{ChangeLog} looks like this:
+ − 1122
+ − 1123 @smallexample
+ − 1124 @group
+ − 1125 Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@@apn.org)
+ − 1126
+ − 1127 * vc.el (vc-do-command): Check call-process status.
+ − 1128 @end group
+ − 1129 @end smallexample
+ − 1130
+ − 1131 When @kbd{C-x v a} adds several change log entries at once, it groups
+ − 1132 related log entries together if they all are checked in by the same
+ − 1133 author at nearly the same time. If the log entries for several such
+ − 1134 files all have the same text, it coalesces them into a single entry.
+ − 1135 For example, suppose the most recent checkins have the following log
+ − 1136 entries:
+ − 1137
+ − 1138 @example
+ − 1139 @exdent For @file{vc.texinfo}:
+ − 1140 Fix expansion typos.
+ − 1141 @exdent For @file{vc.el}:
+ − 1142 Don't call expand-file-name.
+ − 1143 @exdent For @file{vc-hooks.el}:
+ − 1144 Don't call expand-file-name.
+ − 1145 @end example
+ − 1146
+ − 1147 They appear like this in @file{ChangeLog}:
+ − 1148
+ − 1149 @smallexample
+ − 1150 @group
+ − 1151 Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@@apn.org)
+ − 1152
+ − 1153 * vc.texinfo: Fix expansion typos.
+ − 1154
+ − 1155 * vc.el, vc-hooks.el: Don't call expand-file-name.
+ − 1156 @end group
+ − 1157 @end smallexample
+ − 1158
+ − 1159 Normally, @kbd{C-x v a} separates log entries by a blank line, but you
+ − 1160 can mark several related log entries to be clumped together (without an
+ − 1161 intervening blank line) by starting the text of each related log entry
+ − 1162 with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label
+ − 1163 itself is not copied to @file{ChangeLog}. For example, suppose the log
+ − 1164 entries are:
+ − 1165
+ − 1166 @example
+ − 1167 @exdent For @file{vc.texinfo}:
+ − 1168 @{expand@} Fix expansion typos.
+ − 1169 @exdent For @file{vc.el}:
+ − 1170 @{expand@} Don't call expand-file-name.
+ − 1171 @exdent For @file{vc-hooks.el}:
+ − 1172 @{expand@} Don't call expand-file-name.
+ − 1173 @end example
+ − 1174
+ − 1175 @noindent
+ − 1176 Then the text in @file{ChangeLog} looks like this:
+ − 1177
+ − 1178 @smallexample
+ − 1179 @group
+ − 1180 Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@@apn.org)
+ − 1181
+ − 1182 * vc.texinfo: Fix expansion typos.
+ − 1183 * vc.el, vc-hooks.el: Don't call expand-file-name.
+ − 1184 @end group
+ − 1185 @end smallexample
+ − 1186
+ − 1187 A log entry whose text begins with @samp{#} is not copied to
+ − 1188 @file{ChangeLog}. For example, if you merely fix some misspellings in
+ − 1189 comments, you can log the change with an entry beginning with @samp{#}
+ − 1190 to avoid putting such trivia into @file{ChangeLog}.
+ − 1191
+ − 1192 @node Old Versions, VC Status, Change Logs and VC, Version Control
+ − 1193 @subsection Examining And Comparing Old Versions
+ − 1194
+ − 1195 @table @kbd
+ − 1196 @item C-x v ~ @var{version} @key{RET}
+ − 1197 Examine version @var{version} of the visited file, in a buffer of its
+ − 1198 own (@code{vc-version-other-window}).
+ − 1199
+ − 1200 @item C-x v =
+ − 1201 Compare the current buffer contents with the latest checked-in version
+ − 1202 of the file.
+ − 1203
+ − 1204 @item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
+ − 1205 Compare the specified two versions of @var{file}.
+ − 1206 @end table
+ − 1207
+ − 1208 @findex vc-version-other-window
+ − 1209 @kindex C-x v ~
+ − 1210 You can examine any version of a file by first visiting it, and then
+ − 1211 using @kbd{C-x v ~ @var{version} @key{RET}}
+ − 1212 (@code{vc-version-other-window}). This puts the text of version
+ − 1213 @var{version} in a file named @file{@var{filename}.~@var{version}~},
+ − 1214 then visits it in a separate window.
+ − 1215
+ − 1216 @findex vc-diff
+ − 1217 @kindex C-x v =
+ − 1218 To compare two versions of a file, use the command @kbd{C-x v =}
+ − 1219 (@code{vc-diff}).
+ − 1220
+ − 1221 Plain @kbd{C-x v =} compares the current buffer contents (saving them
+ − 1222 in the file if necessary) with the last checked-in version of the file.
+ − 1223 With a prefix argument, @kbd{C-x v =} reads a file name and two version
+ − 1224 numbers, then compares those versions of the specified file.
+ − 1225
+ − 1226 If you supply a directory name instead of the name of a work file,
+ − 1227 this command compares the two specified versions of all registered files
+ − 1228 in that directory and its subdirectories. You can also specify a
+ − 1229 snapshot name (@pxref{Snapshots}) instead of one or both version
+ − 1230 numbers.
+ − 1231
+ − 1232 You can specify a checked-in version by its number; you can specify
+ − 1233 the most recent checked-in version with an empty version number.
+ − 1234
+ − 1235 This command works by running the @code{vcdiff} utility, getting the
+ − 1236 options from the variable @code{diff-switches}. It displays the output
+ − 1237 in a special buffer in another window. Unlike the @kbd{M-x diff}
+ − 1238 command, @kbd{C-x v =} does not try to find the changes in the old and
+ − 1239 new versions. This is because one or both versions normally do not
+ − 1240 exist as files. They exist only in the records of the master file.
+ − 1241 @xref{Comparing Files}, for more information about @kbd{M-x diff}.
+ − 1242
+ − 1243 @node VC Status, Renaming and VC, Old Versions, Version Control
+ − 1244 @subsection VC Status Commands
+ − 1245
+ − 1246 @kindex C-x v l
+ − 1247 @findex vc-print-log
+ − 1248 To view the detailed version control status and history of a file,
+ − 1249 type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of
+ − 1250 changes to the current file, including the text of the log entries. The
+ − 1251 output appears in a separate window.
+ − 1252
+ − 1253 @kindex C-x v d
+ − 1254 @findex vc-directory
+ − 1255 When you are working on a large program, it's often useful to find all
+ − 1256 the files that are currently locked, or all the files maintained in
+ − 1257 version control at all. You can use @kbd{C-x v d} (@code{vc-directory})
+ − 1258 to show all the locked files in or beneath the current directory. This
+ − 1259 includes all files that are locked by any user. @kbd{C-u C-x v d} lists
+ − 1260 all files in or beneath the current directory that are maintained with
+ − 1261 version control.
+ − 1262
+ − 1263 The list of files is displayed as a buffer that uses an augmented
+ − 1264 Dired mode. The names of the users locking various files are shown (in
+ − 1265 parentheses) in place of the owner and group. All the normal Dired
+ − 1266 commands work in this buffer. Most interactive VC commands work also,
+ − 1267 and apply to the file name on the current line.
+ − 1268
+ − 1269 The @kbd{C-x v v} command (@code{vc-next-action}), when used in the
+ − 1270 augmented Dired buffer, operates on all the marked files (or the file on
+ − 1271 the current line). If it operates on more than one file, it handles
+ − 1272 each file according to its current state; thus, it may check out one
+ − 1273 file and check in another (because it is already checked out). If it
+ − 1274 has to check in any files, it reads a single log entry, then uses that
+ − 1275 text for all the files being checked in. This can be convenient for
+ − 1276 registering or checking in several files at once, as part of the same
+ − 1277 change.
+ − 1278
+ − 1279 @node Renaming and VC, Snapshots, VC Status, Version Control
+ − 1280 @subsection Renaming VC Work Files and Master Files
+ − 1281
+ − 1282 @findex vc-rename-file
+ − 1283 When you rename a registered file, you must also rename its master
+ − 1284 file correspondingly to get proper results. Use @code{vc-rename-file}
+ − 1285 to rename the source file as you specify, and rename its master file
+ − 1286 accordingly. It also updates any snapshots (@pxref{Snapshots}) that
+ − 1287 mention the file, so that they use the new name; despite this, the
+ − 1288 snapshot thus modified may not completely work (@pxref{Snapshot
+ − 1289 Caveats}).
+ − 1290
+ − 1291 You cannot use @code{vc-rename-file} on a file that is locked by
+ − 1292 someone else.
+ − 1293
+ − 1294 @node Snapshots, Version Headers, Renaming and VC, Version Control
+ − 1295 @subsection Snapshots
+ − 1296 @cindex snapshots and version control
+ − 1297
+ − 1298 A @dfn{snapshot} is a named set of file versions (one for each
+ − 1299 registered file) that you can treat as a unit. One important kind of
+ − 1300 snapshot is a @dfn{release}, a (theoretically) stable version of the
+ − 1301 system that is ready for distribution to users.
+ − 1302
+ − 1303 @menu
+ − 1304 * Making Snapshots:: The snapshot facilities.
+ − 1305 * Snapshot Caveats:: Things to be careful of when using snapshots.
+ − 1306 @end menu
+ − 1307
+ − 1308 @node Making Snapshots, Snapshot Caveats, Snapshots, Snapshots
+ − 1309 @subsubsection Making and Using Snapshots
+ − 1310
+ − 1311 There are two basic commands for snapshots; one makes a
+ − 1312 snapshot with a given name, the other retrieves a named snapshot.
+ − 1313
+ − 1314 @table @code
+ − 1315 @kindex C-x v s
+ − 1316 @findex vc-create-snapshot
+ − 1317 @item C-x v s @var{name} @key{RET}
+ − 1318 Define the last saved versions of every registered file in or under the
+ − 1319 current directory as a snapshot named @var{name}
+ − 1320 (@code{vc-create-snapshot}).
+ − 1321
+ − 1322 @kindex C-x v r
+ − 1323 @findex vc-retrieve-snapshot
+ − 1324 @item C-x v r @var{name} @key{RET}
+ − 1325 Check out all registered files at or below the current directory level
+ − 1326 using whatever versions correspond to the snapshot @var{name}
+ − 1327 (@code{vc-retrieve-snapshot}).
+ − 1328
+ − 1329 This command reports an error if any files are locked at or below the
+ − 1330 current directory, without changing anything; this is to avoid
+ − 1331 overwriting work in progress.
+ − 1332 @end table
+ − 1333
+ − 1334 A snapshot uses a very small amount of resources---just enough to record
+ − 1335 the list of file names and which version belongs to the snapshot. Thus,
+ − 1336 you need not hesitate to create snapshots whenever they are useful.
+ − 1337
+ − 1338 You can give a snapshot name as an argument to @kbd{C-x v =} or
+ − 1339 @kbd{C-x v ~} (@pxref{Old Versions}). Thus, you can use it to compare a
+ − 1340 snapshot against the current files, or two snapshots against each other,
+ − 1341 or a snapshot against a named version.
+ − 1342
+ − 1343 @node Snapshot Caveats, , Making Snapshots, Snapshots
+ − 1344 @subsubsection Snapshot Caveats
+ − 1345
+ − 1346 @cindex named configurations (RCS)
+ − 1347 VC's snapshot facilities are modeled on RCS's named-configuration
+ − 1348 support. They use RCS's native facilities for this, so under VC
+ − 1349 snapshots made using RCS are visible even when you bypass VC.
+ − 1350
+ − 1351 @c worded verbosely to avoid overfull hbox.
+ − 1352 For SCCS, VC implements snapshots itself. The files it uses contain
+ − 1353 name/file/version-number triples. These snapshots are visible only
+ − 1354 through VC.
+ − 1355
+ − 1356 A snapshot is a set of checked-in versions. So make sure that all the
+ − 1357 files are checked in and not locked when you make a snapshot.
+ − 1358
+ − 1359 File renaming and deletion can create some difficulties with snapshots.
+ − 1360 This is not a VC-specific problem, but a general design issue in version
+ − 1361 control systems that no one has solved very well yet.
+ − 1362
+ − 1363 If you rename a registered file, you need to rename its master along
+ − 1364 with it (the command @code{vc-rename-file} does this automatically). If
+ − 1365 you are using SCCS, you must also update the records of the snapshot, to
+ − 1366 mention the file by its new name (@code{vc-rename-file} does this,
+ − 1367 too). An old snapshot that refers to a master file that no longer
+ − 1368 exists under the recorded name is invalid; VC can no longer retrieve
+ − 1369 it. It would be beyond the scope of this manual to explain enough about
+ − 1370 RCS and SCCS to explain how to update the snapshots by hand.
+ − 1371
+ − 1372 Using @code{vc-rename-file} makes the snapshot remain valid for
+ − 1373 retrieval, but it does not solve all problems. For example, some of the
+ − 1374 files in the program probably refer to others by name. At the very
+ − 1375 least, the makefile probably mentions the file that you renamed. If you
+ − 1376 retrieve an old snapshot, the renamed file is retrieved under its new
+ − 1377 name, which is not the name that the makefile expects. So the program
+ − 1378 won't really work as retrieved.
+ − 1379
+ − 1380 @node Version Headers, , Snapshots, Version Control
+ − 1381 @subsection Inserting Version Control Headers
+ − 1382
+ − 1383 Sometimes it is convenient to put version identification strings
+ − 1384 directly into working files. Certain special strings called
+ − 1385 @dfn{version headers} are replaced in each successive version by the
+ − 1386 number of that version.
+ − 1387
+ − 1388 @kindex C-x v h
+ − 1389 @findex vc-insert-headers
+ − 1390 You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
+ − 1391 insert a suitable header string.
+ − 1392
+ − 1393 @table @kbd
+ − 1394 @item C-x v h
+ − 1395 Insert headers in a file for use with your version-control system.
+ − 1396 @end table
+ − 1397
+ − 1398 @vindex vc-header-alist
+ − 1399 The default header string is @samp{\$Id\$} for RCS and @samp{\%W\%}
+ − 1400 for SCCS. (The actual strings inserted do not have the backslashes
+ − 1401 in them. They were placed in the Info source file so that the
+ − 1402 strings don't get interpreted as version-control headers when the
+ − 1403 Info source files are maintained under version control.) You can
+ − 1404 specify other headers to insert by setting the variable
+ − 1405 @code{vc-header-alist}. Its value is a list of elements of the form
+ − 1406 @code{(@var{program} . @var{string})} where @var{program} is @code{RCS}
+ − 1407 or @code{SCCS} and @var{string} is the string to use.
+ − 1408
+ − 1409 Instead of a single string, you can specify a list of strings; then
+ − 1410 each string in the list is inserted as a separate header on a line of
+ − 1411 its own.
+ − 1412
+ − 1413 It is often necessary to use ``superfluous'' backslashes when writing
+ − 1414 the strings that you put in this variable. This is to prevent the
+ − 1415 string in the constant from being interpreted as a header itself if the
+ − 1416 Emacs Lisp file containing it is maintained with version control.
+ − 1417
+ − 1418 @vindex vc-comment-alist
+ − 1419 Each header is inserted surrounded by tabs, inside comment delimiters,
+ − 1420 on a new line at the start of the buffer. Normally the ordinary comment
+ − 1421 start and comment end strings of the current mode are used, but for
+ − 1422 certain modes, there are special comment delimiters for this purpose;
+ − 1423 the variable @code{vc-comment-alist} specifies them. Each element of
+ − 1424 this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
+ − 1425
+ − 1426 @vindex vc-static-header-alist
+ − 1427 The variable @code{vc-static-header-alist} specifies further strings
+ − 1428 to add based on the name of the buffer. Its value should be a list of
+ − 1429 elements of the form @code{(@var{regexp} . @var{format})}. Whenever
+ − 1430 @var{regexp} matches the buffer name, @var{format} is inserted as part
+ − 1431 of the header. A header line is inserted for each element that matches
+ − 1432 the buffer name, and for each string specified by
+ − 1433 @code{vc-header-alist}. The header line is made by processing the
+ − 1434 string from @code{vc-header-alist} with the format taken from the
+ − 1435 element. The default value for @code{vc-static-header-alist} is:
+ − 1436
+ − 1437 @example
+ − 1438 @group
+ − 1439 (("\\.c$" .
+ − 1440 "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
+ − 1441 #endif /* lint */\n"))
+ − 1442 @end group
+ − 1443 @end example
+ − 1444
+ − 1445 @noindent
+ − 1446 which specifies insertion of a string of this form:
+ − 1447
+ − 1448 @example
+ − 1449 @group
+ − 1450
+ − 1451 #ifndef lint
+ − 1452 static char vcid[] = "@var{string}";
+ − 1453 #endif /* lint */
+ − 1454 @end group
+ − 1455 @end example
+ − 1456
+ − 1457 @node ListDir, Comparing Files, Version Control, Files
+ − 1458 @section Listing a File Directory
+ − 1459
+ − 1460 @cindex file directory
+ − 1461 @cindex directory listing
+ − 1462 Files are organized by Unix into @dfn{directories}. A @dfn{directory
+ − 1463 listing} is a list of all the files in a directory. Emacs provides
+ − 1464 directory listings in brief format (file names only) and verbose format
+ − 1465 (sizes, dates, and authors included).
+ − 1466
+ − 1467 @table @kbd
+ − 1468 @item C-x C-d @var{dir-or-pattern}
+ − 1469 Print a brief directory listing (@code{list-directory}).
+ − 1470 @item C-u C-x C-d @var{dir-or-pattern}
+ − 1471 Print a verbose directory listing.
+ − 1472 @end table
+ − 1473
+ − 1474 @findex list-directory
+ − 1475 @kindex C-x C-d
+ − 1476 To print a directory listing, use @kbd{C-x C-d}
+ − 1477 (@code{list-directory}). This command prompts in the minibuffer for a
+ − 1478 file name which is either a directory to be listed or pattern
+ − 1479 containing wildcards for the files to be listed. For example,
+ − 1480
+ − 1481 @example
+ − 1482 C-x C-d /u2/emacs/etc @key{RET}
+ − 1483 @end example
+ − 1484
+ − 1485 @noindent
+ − 1486 lists all the files in directory @file{/u2/emacs/etc}. An example of
+ − 1487 specifying a file name pattern is:
+ − 1488
+ − 1489 @example
+ − 1490 C-x C-d /u2/emacs/src/*.c @key{RET}
+ − 1491 @end example
+ − 1492
+ − 1493 Normally, @kbd{C-x C-d} prints a brief directory listing containing just
+ − 1494 file names. A numeric argument (regardless of value) tells it to print a
+ − 1495 verbose listing (like @code{ls -l}).
+ − 1496
+ − 1497 @vindex list-directory-brief-switches
+ − 1498 @vindex list-directory-verbose-switches
+ − 1499 Emacs obtains the text of a directory listing by running @code{ls} in
+ − 1500 an inferior process. Two Emacs variables control the switches passed to
+ − 1501 @code{ls}: @code{list-directory-brief-switches} is a string giving the
+ − 1502 switches to use in brief listings (@code{"-CF"} by default).
+ − 1503 @code{list-directory-verbose-switches} is a string giving the switches
+ − 1504 to use in a verbose listing (@code{"-l"} by default).
+ − 1505
+ − 1506 The variable @code{directory-abbrev-alist} is an alist of abbreviations
+ − 1507 for file directories. The list consists of elements of the form
+ − 1508 @code{(FROM . TO)}, each meaning to replace @code{FROM} with @code{TO}
+ − 1509 when it appears in a directory name. This replacement is done when
+ − 1510 setting up the default directory of a newly visited file. Every @code{FROM}
+ − 1511 string should start with `@samp{^}'.
+ − 1512
+ − 1513 Use this feature when you have directories which you normally refer to
+ − 1514 via absolute symbolic links. Make @code{TO} the name of the link, and
+ − 1515 @code{FROM} the name it is linked to.
+ − 1516
+ − 1517 @node Comparing Files, Dired, ListDir, Files
+ − 1518 @section Comparing Files
+ − 1519 @cindex comparing files
+ − 1520
+ − 1521 @findex diff
+ − 1522 @vindex diff-switches
+ − 1523 The command @kbd{M-x diff} compares two files, displaying the
+ − 1524 differences in an Emacs buffer named @samp{*Diff*}. It works by running
+ − 1525 the @code{diff} program, using options taken from the variable
+ − 1526 @code{diff-switches}, whose value should be a string.
+ − 1527
+ − 1528 The buffer @samp{*Diff*} has Compilation mode as its major mode, so
+ − 1529 you can use @kbd{C-x `} to visit successive changed locations in the two
+ − 1530 source files. You can also move to a particular hunk of changes and
+ − 1531 type @kbd{C-c C-c} to find the corresponding source location. You can
+ − 1532 also use the other special commands of Compilation mode: @key{SPC} and
+ − 1533 @key{DEL} for scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion.
+ − 1534 @xref{Compilation}.
+ − 1535
+ − 1536 @findex diff-backup
+ − 1537 The command @kbd{M-x diff-backup} compares a specified file with its most
+ − 1538 recent backup. If you specify the name of a backup file,
+ − 1539 @code{diff-backup} compares it with the source file that it is a backup
+ − 1540 of.
+ − 1541
+ − 1542 @findex compare-windows
+ − 1543 @cindex comparing files
+ − 1544 The command @kbd{M-x compare-windows} compares the text in the current
+ − 1545 window with that in the next window. Comparison starts at point in each
+ − 1546 window. Point moves forward in each window, a character at a time in each
+ − 1547 window, until the next characters in the two windows are different. Then
+ − 1548 the command is finished. For more information about windows in Emacs,
+ − 1549 @ref{Windows}.
+ − 1550
+ − 1551 @vindex compare-ignore-case
+ − 1552 With a numeric argument, @code{compare-windows} ignores changes in
+ − 1553 whitespace. If the variable @code{compare-ignore-case} is
+ − 1554 non-@code{nil}, it ignores differences in case as well.
+ − 1555
+ − 1556 @node Dired, Misc File Ops, Comparing Files, Files
+ − 1557 @section Dired, the Directory Editor
+ − 1558 @cindex Dired
+ − 1559 @cindex deletion (of files)
+ − 1560
+ − 1561 Dired makes it easy to delete or visit many of the files in a single
+ − 1562 directory at once. It creates an Emacs buffer containing a listing of the
+ − 1563 directory. You can use the normal Emacs commands to move around in this
+ − 1564 buffer and special Dired commands to operate on the files.
+ − 1565
+ − 1566 @menu
+ − 1567 * Enter: Dired Enter. How to invoke Dired.
+ − 1568 * Edit: Dired Edit. Editing the Dired buffer.
+ − 1569 * Deletion: Dired Deletion. Deleting files with Dired.
+ − 1570 * Immed: Dired Immed. Other file operations through Dired.
+ − 1571 @end menu
+ − 1572
+ − 1573 @node Dired Enter, Dired Edit, Dired, Dired
+ − 1574 @subsection Entering Dired
+ − 1575
+ − 1576 @findex dired
+ − 1577 @kindex C-x d
+ − 1578 @vindex dired-listing-switches
+ − 1579 To invoke dired, type @kbd{C-x d} or @kbd{M-x dired}. The command reads a
+ − 1580 directory name or wildcard file name pattern as a minibuffer argument just
+ − 1581 like the @code{list-directory} command, @kbd{C-x C-d}. Where @code{dired}
+ − 1582 differs from @code{list-directory} is in naming the buffer after the
+ − 1583 directory name or the wildcard pattern used for the listing, and putting
+ − 1584 the buffer into Dired mode so that the special commands of Dired are
+ − 1585 available in it. The variable @code{dired-listing-switches} is a string
+ − 1586 used as an argument to @code{ls} in making the directory; this string
+ − 1587 @i{must} contain @samp{-l}.
+ − 1588
+ − 1589 @findex dired-other-window
+ − 1590 @kindex C-x 4 d
+ − 1591 To display the Dired buffer in another window rather than in the selected
+ − 1592 window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead of @kbd{C-x d}.
+ − 1593
+ − 1594 @node Dired Edit, Dired Deletion, Dired Enter, Dired
+ − 1595 @subsection Editing in Dired
+ − 1596
+ − 1597 Once the Dired buffer exists, you can switch freely between it and other
+ − 1598 Emacs buffers. Whenever the Dired buffer is selected, certain special
+ − 1599 commands are provided that operate on files that are listed. The Dired
+ − 1600 buffer is ``read-only'', and inserting text in it is not useful, so
+ − 1601 ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired
+ − 1602 commands. Most Dired commands operate on the file described by the line
+ − 1603 that point is on. Some commands perform operations immediately; others
+ − 1604 ``flag'' a file to be operated on later.
+ − 1605
+ − 1606 Most Dired commands that operate on the current line's file also treat a
+ − 1607 numeric argument as a repeat count, meaning to act on the files of the
+ − 1608 next few lines. A negative argument means to operate on the files of the
+ − 1609 preceding lines, and leave point on the first of those lines.
+ − 1610
+ − 1611 All the usual Emacs cursor motion commands are available in Dired
+ − 1612 buffers. Some special purpose commands are also provided. The keys
+ − 1613 @kbd{C-n} and @kbd{C-p} are redefined so that they try to position
+ − 1614 the cursor at the beginning of the filename on the line, rather than
+ − 1615 at the beginning of the line.
+ − 1616
+ − 1617 For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to
+ − 1618 @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. Moving by lines is done so
+ − 1619 often in Dired that it deserves to be easy to type. @key{DEL} (move up and
+ − 1620 unflag) is often useful simply for moving up.@refill
+ − 1621
+ − 1622 The @kbd{g} command in Dired runs @code{revert-buffer} to reinitialize
+ − 1623 the buffer from the actual disk directory and show any changes made in the
+ − 1624 directory by programs other than Dired. All deletion flags in the Dired
+ − 1625 buffer are lost when this is done.
+ − 1626
+ − 1627 @node Dired Deletion, Dired Immed, Dired Edit, Dired
+ − 1628 @subsection Deleting Files With Dired
+ − 1629
+ − 1630 The primary use of Dired is to flag files for deletion and then delete
+ − 1631 them.
+ − 1632
+ − 1633 @table @kbd
+ − 1634 @item d
+ − 1635 Flag this file for deletion.
+ − 1636 @item u
+ − 1637 Remove deletion-flag on this line.
+ − 1638 @item @key{DEL}
+ − 1639 Remove deletion-flag on previous line, moving point to that line.
+ − 1640 @item x
+ − 1641 Delete the files that are flagged for deletion.
+ − 1642 @item #
+ − 1643 Flag all auto-save files (files whose names start and end with @samp{#})
+ − 1644 for deletion (@pxref{Auto Save}).
+ − 1645 @item ~
+ − 1646 Flag all backup files (files whose names end with @samp{~}) for deletion
+ − 1647 (@pxref{Backup}).
+ − 1648 @item .@: @r{(Period)}
+ − 1649 Flag excess numeric backup files for deletion. The oldest and newest
+ − 1650 few backup files of any one file are exempt; the middle ones are flagged.
+ − 1651 @end table
+ − 1652
+ − 1653 You can flag a file for deletion by moving to the line describing the
+ − 1654 file and typing @kbd{d} or @kbd{C-d}. The deletion flag is visible as a
+ − 1655 @samp{D} at the beginning of the line. Point is moved to the beginning of
+ − 1656 the next line, so that repeated @kbd{d} commands flag successive files.
+ − 1657
+ − 1658 The files are flagged for deletion rather than deleted immediately to
+ − 1659 avoid the danger of deleting a file accidentally. Until you direct Dired
+ − 1660 to delete the flagged files, you can remove deletion flags using the
+ − 1661 commands @kbd{u} and @key{DEL}. @kbd{u} works just like @kbd{d}, but
+ − 1662 removes flags rather than making flags. @key{DEL} moves upward, removing
+ − 1663 flags; it is like @kbd{u} with numeric argument automatically negated.
+ − 1664
+ − 1665 To delete the flagged files, type @kbd{x}. This command first displays a
+ − 1666 list of all the file names flagged for deletion, and requests confirmation
+ − 1667 with @kbd{yes}. Once you confirm, all the flagged files are deleted, and their
+ − 1668 lines are deleted from the text of the Dired buffer. The shortened Dired
+ − 1669 buffer remains selected. If you answer @kbd{no} or quit with @kbd{C-g}, you
+ − 1670 return immediately to Dired, with the deletion flags still present and no
+ − 1671 files actually deleted.
+ − 1672
+ − 1673 The @kbd{#}, @kbd{~}, and @kbd{.} commands flag many files for
+ − 1674 deletion, based on their names. These commands are useful precisely
+ − 1675 because they do not actually delete any files; you can remove the
+ − 1676 deletion flags from any flagged files that you really wish to keep.@refill
+ − 1677
+ − 1678 @kbd{#} flags for deletion all files that appear to have been made by
+ − 1679 auto-saving (that is, files whose names begin and end with @samp{#}).
+ − 1680 @kbd{~} flags for deletion all files that appear to have been made as
+ − 1681 backups for files that were edited (that is, files whose names end with
+ − 1682 @samp{~}).
+ − 1683
+ − 1684 @vindex dired-kept-versions
+ − 1685 @kbd{.} (Period) flags just some of the backup files for deletion: only
+ − 1686 numeric backups that are not among the oldest few nor the newest few
+ − 1687 backups of any one file. Normally @code{dired-kept-versions} (not
+ − 1688 @code{kept-new-versions}; that applies only when saving) specifies the
+ − 1689 number of newest versions of each file to keep, and
+ − 1690 @code{kept-old-versions} specifies the number of oldest versions to keep.
+ − 1691 Period with a positive numeric argument, as in @kbd{C-u 3 .}, specifies the
+ − 1692 number of newest versions to keep, overriding @code{dired-kept-versions}.
+ − 1693 A negative numeric argument overrides @code{kept-old-versions}, using minus
+ − 1694 the value of the argument to specify the number of oldest versions of each
+ − 1695 file to keep.@refill
+ − 1696
+ − 1697 @node Dired Immed, , Dired Deletion, Dired
+ − 1698 @subsection Immediate File Operations in Dired
+ − 1699
+ − 1700 Some file operations in Dired take place immediately when they are
+ − 1701 requested.
+ − 1702
+ − 1703 @table @kbd
+ − 1704 @item C
+ − 1705 Copies the file described on the current line. You must supply a file name
+ − 1706 to copy to, using the minibuffer.
+ − 1707 @item f
+ − 1708 Visits the file described on the current line. It is just like typing
+ − 1709 @kbd{C-x C-f} and supplying that file name. If the file on this line is a
+ − 1710 subdirectory, @kbd{f} actually causes Dired to be invoked on that
+ − 1711 subdirectory. @xref{Visiting}.
+ − 1712 @item o
+ − 1713 Like @kbd{f}, but uses another window to display the file's buffer. The
+ − 1714 Dired buffer remains visible in the first window. This is like using
+ − 1715 @kbd{C-x 4 C-f} to visit the file. @xref{Windows}.
+ − 1716 @item R
+ − 1717 Renames the file described on the current line. You must supply a file
+ − 1718 name to rename to, using the minibuffer.
+ − 1719 @item v
+ − 1720 Views the file described on this line using @kbd{M-x view-file}. Viewing a
+ − 1721 file is like visiting it, but is slanted toward moving around in the file
+ − 1722 conveniently and does not allow changing the file. @xref{Misc File
+ − 1723 Ops,View File}. Viewing a file that is a directory runs Dired on that
+ − 1724 directory.@refill
+ − 1725 @end table
+ − 1726
+ − 1727 @node Misc File Ops, , Dired, Files
+ − 1728 @section Miscellaneous File Operations
+ − 1729
+ − 1730 Emacs has commands for performing many other operations on files.
+ − 1731 All operate on one file; they do not accept wildcard file names.
+ − 1732
+ − 1733 @findex add-name-to-file
+ − 1734 You can use the command @kbd{M-x add-name-to-file} to add a name to an
+ − 1735 existing file without removing the old name. The new name must belong
+ − 1736 on the file system that the file is on.
+ − 1737
+ − 1738 @findex append-to-file
+ − 1739 @kbd{M-x append-to-file} adds the text of the region to the end of the
+ − 1740 specified file.
+ − 1741
+ − 1742 @findex copy-file
+ − 1743 @cindex copying files
+ − 1744 @kbd{M-x copy-file} reads the file @var{old} and writes a new file
+ − 1745 named @var{new} with the same contents. Confirmation is required if a
+ − 1746 file named @var{new} already exists, because copying overwrites the old
+ − 1747 contents of the file @var{new}.
+ − 1748
+ − 1749 @findex delete-file
+ − 1750 @cindex deletion (of files)
+ − 1751 @kbd{M-x delete-file} deletes a specified file, like the @code{rm}
+ − 1752 command in the shell. If you are deleting many files in one directory, it
+ − 1753 may be more convenient to use Dired (@pxref{Dired}).
+ − 1754
+ − 1755 @findex insert-file
+ − 1756 @kbd{M-x insert-file} inserts a copy of the contents of a specified
+ − 1757 file into the current buffer at point, leaving point unchanged before the
+ − 1758 contents and the mark after them. @xref{Mark}.
+ − 1759
+ − 1760 @findex make-symbolic-link
+ − 1761 @kbd{M-x make-symbolic-link} reads two file names @var{old} and
+ − 1762 @var{linkname}, and then creates a symbolic link named @var{linkname}
+ − 1763 and pointing at @var{old}. Future attempts to open file
+ − 1764 @var{linkname} will then refer to the file named @var{old} at the time
+ − 1765 the opening is done, or will result in an error if the name @var{old} is
+ − 1766 not in use at that time. Confirmation is required if you create the
+ − 1767 link while @var{linkname} is in use. Note that not all systems support
+ − 1768 symbolic links.
+ − 1769
+ − 1770 @findex rename-file
+ − 1771 @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
+ − 1772 the minibuffer, then renames file @var{old} as @var{new}. If a file named
+ − 1773 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
+ − 1774 done; this is because renaming causes the previous meaning of the
+ − 1775 name @var{new} to be lost. If @var{old} and @var{new} are on different
+ − 1776 file systems, the file @var{old} is copied and deleted.
+ − 1777
+ − 1778 @findex view-file
+ − 1779 @cindex viewing
+ − 1780 @kbd{M-x view-file} allows you to scan or read a file by sequential
+ − 1781 screenfuls. It reads a file name argument using the minibuffer. After
+ − 1782 reading the file into an Emacs buffer, @code{view-file} reads and displays
+ − 1783 one windowful. You can then type @key{SPC} to scroll forward one window,
+ − 1784 or @key{DEL} to scroll backward. Various other commands are provided for
+ − 1785 moving around in the file, but none for changing it; type @kbd{C-h} while
+ − 1786 viewing a file for a list of them. Most commands are the default Emacs
+ − 1787 cursor motion commands. To exit from viewing, type @kbd{C-c}.
