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