diff options
Diffstat (limited to 'man/files.texi')
| -rw-r--r-- | man/files.texi | 2413 |
1 files changed, 2413 insertions, 0 deletions
diff --git a/man/files.texi b/man/files.texi new file mode 100644 index 00000000000..375615731d2 --- /dev/null +++ b/man/files.texi @@ -0,0 +1,2413 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Files, Buffers, Fixit, Top +@chapter File Handling +@cindex files + + The operating system stores data permanently in named @dfn{files}. So +most of the text you edit with Emacs comes from a file and is ultimately +stored in a file. + + To edit a file, you must tell Emacs to read the file and prepare a +buffer containing a copy of the file's text. This is called +@dfn{visiting} the file. Editing commands apply directly to text in the +buffer; that is, to the copy inside Emacs. Your changes appear in the +file itself only when you @dfn{save} the buffer back into the file. + + In addition to visiting and saving files, Emacs can delete, copy, +rename, and append to files, keep multiple versions of them, and operate +on file directories. + +@menu +* File Names:: How to type and edit file-name arguments. +* Visiting:: Visiting a file prepares Emacs to edit the file. +* Saving:: Saving makes your changes permanent. +* Reverting:: Reverting cancels all the changes not saved. +* Auto Save:: Auto Save periodically protects against loss of data. +* File Aliases:: Handling multiple names for one file. +* Version Control:: Version control systems (RCS, CVS and SCCS). +* Directories:: Creating, deleting, and listing file directories. +* Comparing Files:: Finding where two files differ. +* Misc File Ops:: Other things you can do on files. +* Compressed Files:: Accessing compressed files. +* Remote Files:: Accessing files on other sites. +* Quoted File Names:: Quoting special characters in file names. +@end menu + +@node File Names +@section File Names +@cindex file names + + Most Emacs commands that operate on a file require you to specify the +file name. (Saving and reverting are exceptions; the buffer knows which +file name to use for them.) You enter the file name using the +minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available, to make +it easier to specify long file names. @xref{Completion}. + + For most operations, there is a @dfn{default file name} which is used +if you type just @key{RET} to enter an empty argument. Normally the +default file name is the name of the file visited in the current buffer; +this makes it easy to operate on that file with any of the Emacs file +commands. + +@vindex default-directory + Each buffer has a default directory, normally the same as the +directory of the file visited in that buffer. When you enter a file +name without a directory, the default directory is used. If you specify +a directory in a relative fashion, with a name that does not start with +a slash, it is interpreted with respect to the default directory. The +default directory is kept in the variable @code{default-directory}, +which has a separate value in every buffer. + + For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then +the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo}, +which does not specify a directory, it is short for @file{/u/rms/gnu/foo}. +@samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo} +would stand for the file name @file{/u/rms/gnu/new/foo}. + +@findex cd +@findex pwd + The command @kbd{M-x pwd} prints the current buffer's default +directory, and the command @kbd{M-x cd} sets it (to a value read using +the minibuffer). A buffer's default directory changes only when the +@code{cd} command is used. A file-visiting buffer's default directory +is initialized to the directory of the file that is visited there. If +you create a buffer with @kbd{C-x b}, its default directory is copied +from that of the buffer that was current at the time. + +@vindex insert-default-directory + The default directory actually appears in the minibuffer when the +minibuffer becomes active to read a file name. This serves two +purposes: it @emph{shows} you what the default is, so that you can type +a relative file name and know with certainty what it will mean, and it +allows you to @emph{edit} the default to specify a different directory. +This insertion of the default directory is inhibited if the variable +@code{insert-default-directory} is set to @code{nil}. + + Note that it is legitimate to type an absolute file name after you +enter the minibuffer, ignoring the presence of the default directory +name as part of the text. The final minibuffer contents may look +invalid, but that is not so. For example, if the minibuffer starts out +with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get +@samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the +first slash in the double slash; the result is @samp{/x1/rms/foo}. +@xref{Minibuffer File}. + + @samp{$} in a file name is used to substitute environment variables. +For example, if you have used the shell command @samp{export +FOO=rms/hacks} to set up an environment variable named @code{FOO}, then +you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an +abbreviation for @file{/u/rms/hacks/test.c}. The environment variable +name consists of all the alphanumeric characters after the @samp{$}; +alternatively, it may be enclosed in braces after the @samp{$}. Note +that shell commands to set environment variables affect Emacs only if +done before Emacs is started. + + To access a file with @samp{$} in its name, type @samp{$$}. This pair +is converted to a single @samp{$} at the same time as variable +substitution is performed for single @samp{$}. Alternatively, quote the +whole file name with @samp{/:} (@pxref{Quoted File Names}). + +@findex substitute-in-file-name + The Lisp function that performs the substitution is called +@code{substitute-in-file-name}. The substitution is performed only on +file names read as such using the minibuffer. + + You can include non-ASCII characters in file names if you set the +variable @code{file-name-coding-system} to a non-@code{nil} value. +@xref{Specify Coding}. + +@node Visiting +@section Visiting Files +@cindex visiting files + +@c WideCommands +@table @kbd +@item C-x C-f +Visit a file (@code{find-file}). +@item C-x C-r +Visit a file for viewing, without allowing changes to it +(@code{find-file-read-only}). +@item C-x C-v +Visit a different file instead of the one visited last +(@code{find-alternate-file}). +@item C-x 4 f +Visit a file, in another window (@code{find-file-other-window}). Don't +alter what is displayed in the selected window. +@item C-x 5 f +Visit a file, in a new frame (@code{find-file-other-frame}). Don't +alter what is displayed in the selected frame. +@item M-x find-file-literally +Visit a file with no conversion of the contents. +@end table + +@cindex files, visiting and saving +@cindex visiting files +@cindex saving files + @dfn{Visiting} a file means copying its contents into an Emacs buffer +so you can edit them. Emacs makes a new buffer for each file that you +visit. We say that this buffer is visiting the file that it was created +to hold. Emacs constructs the buffer name from the file name by +throwing away the directory, keeping just the name proper. For example, +a file named @file{/usr/rms/emacs.tex} would get a buffer named +@samp{emacs.tex}. If there is already a buffer with that name, a unique +name is constructed by appending @samp{<2>}, @samp{<3>}, or so on, using +the lowest number that makes a name that is not already in use. + + Each window's mode line shows the name of the buffer that is being displayed +in that window, so you can always tell what buffer you are editing. + + The changes you make with editing commands are made in the Emacs +buffer. They do not take effect in the file that you visited, or any +place permanent, until you @dfn{save} the buffer. Saving the buffer +means that Emacs writes the current contents of the buffer into its +visited file. @xref{Saving}. + +@cindex modified (buffer) + If a buffer contains changes that have not been saved, we say the +buffer is @dfn{modified}. This is important because it implies that +some changes will be lost if the buffer is not saved. The mode line +displays two stars near the left margin to indicate that the buffer is +modified. + +@kindex C-x C-f +@findex find-file + To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow +the command with the name of the file you wish to visit, terminated by a +@key{RET}. + + The file name is read using the minibuffer (@pxref{Minibuffer}), with +defaulting and completion in the standard manner (@pxref{File Names}). +While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}. + + Your confirmation that @kbd{C-x C-f} has completed successfully is the +appearance of new text on the screen and a new buffer name in the mode +line. If the specified file does not exist and could not be created, or +cannot be read, then you get an error, with an error message displayed +in the echo area. + + If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make +another copy. It selects the existing buffer containing that file. +However, before doing so, it checks that the file itself has not changed +since you visited or saved it last. If the file has changed, a warning +message is printed. @xref{Interlocking,,Simultaneous Editing}. + +@cindex creating files + What if you want to create a new file? Just visit it. Emacs prints +@samp{(New File)} in the echo area, but in other respects behaves as if +you had visited an existing empty file. If you make any changes and +save them, the file is created. + + Emacs recognizes from the contents of a file which convention it uses +to separate lines---newline (used on GNU/Linux and on Unix), +carriage-return linefeed (used on Microsoft systems), or just +carriage-return (used on the Macintosh)---and automatically converts the +contents to the normal Emacs convention, which is that the newline +character separates lines. This is a part of the general feature of +coding system conversion (@pxref{Coding Systems}), and makes it possible +to edit files imported from various different operating systems with +equal convenience. If you change the text and save the file, Emacs +performs the inverse conversion, changing newlines back into +carriage-return linefeed or just carriage-return if appropriate. + +@vindex find-file-run-dired + If the file you specify is actually a directory, @kbd{C-x C-f} invokes +Dired, the Emacs directory browser, so that you can ``edit'' the contents +of the directory (@pxref{Dired}). Dired is a convenient way to delete, +look at, or operate on the files in the directory. However, if the +variable @code{find-file-run-dired} is @code{nil}, then it is an error +to try to visit a directory. + + If the file name you specify contains wildcard characters, Emacs +visits all the files that match it. @xref{Quoted File Names}, if you +want to visit a file whose name actually contains wildcard characters. + + If you visit a file that the operating system won't let you modify, +Emacs makes the buffer read-only, so that you won't go ahead and make +changes that you'll have trouble saving afterward. You can make the +buffer writable with @kbd{C-x C-q} (@code{vc-toggle-read-only}). +@xref{Misc Buffer}. + +@kindex C-x C-r +@findex find-file-read-only + Occasionally you might want to visit a file as read-only in order to +protect yourself from entering changes accidentally; do so by visiting +the file with the command @kbd{C-x C-r} (@code{find-file-read-only}). + +@kindex C-x C-v +@findex find-alternate-file + If you visit a nonexistent file unintentionally (because you typed the +wrong file name), use the @kbd{C-x C-v} command +(@code{find-alternate-file}) to visit the file you really wanted. +@kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current +buffer (after first offering to save it if it is modified). When it +reads the file name to visit, it inserts the entire default file name in +the buffer, with point just after the directory part; this is convenient +if you made a slight error in typing the name. + + If you find a file which exists but cannot be read, @kbd{C-x C-f} +signals an error. + +@kindex C-x 4 f +@findex find-file-other-window + @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} +except that the buffer containing the specified file is selected in another +window. The window that was selected before @kbd{C-x 4 f} continues to +show the same buffer it was already showing. If this command is used when +only one window is being displayed, that window is split in two, with one +window showing the same buffer as before, and the other one showing the +newly requested file. @xref{Windows}. + +@kindex C-x 5 f +@findex find-file-other-frame + @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a +new frame, or makes visible any existing frame showing the file you +seek. This feature is available only when you are using a window +system. @xref{Frames}. + +@findex find-file-literally + If you wish to edit a file as a sequence of characters with no special +encoding or conversion, use the @kbd{M-x find-file-literally} command. +It visits a file, like @kbd{C-x C-f}, but does not do format conversion +(@pxref{Formatted Text}), character code conversion (@pxref{Coding +Systems}), or automatic uncompression (@pxref{Compressed Files}). +If you already have visited the same file in the usual (non-literal) +manner, this command asks you whether to visit it literally instead. + +@vindex find-file-hooks +@vindex find-file-not-found-hooks + Two special hook variables allow extensions to modify the operation of +visiting files. Visiting a file that does not exist runs the functions +in the list @code{find-file-not-found-hooks}; this variable holds a list +of functions, and the functions are called one by one (with no +arguments) until one of them returns non-@code{nil}. This is not a +normal hook, and the name ends in @samp{-hooks} rather than @samp{-hook} +to indicate that fact. + + Any visiting of a file, whether extant or not, expects +@code{find-file-hooks} to contain a list of functions, and calls them +all, one by one, with no arguments. This variable is really a normal +hook, but it has an abnormal name for historical compatibility. In the +case of a nonexistent file, the @code{find-file-not-found-hooks} are run +first. @xref{Hooks}. + + There are several ways to specify automatically the major mode for +editing the file (@pxref{Choosing Modes}), and to specify local +variables defined for that file (@pxref{File Variables}). + +@node Saving +@section Saving Files + + @dfn{Saving} a buffer in Emacs means writing its contents back into the file +that was visited in the buffer. + +@table @kbd +@item C-x C-s +Save the current buffer in its visited file (@code{save-buffer}). +@item C-x s +Save any or all buffers in their visited files (@code{save-some-buffers}). +@item M-~ +Forget that the current buffer has been changed (@code{not-modified}). +@item C-x C-w +Save the current buffer in a specified file (@code{write-file}). +@item M-x set-visited-file-name +Change file the name under which the current buffer will be saved. +@end table + +@kindex C-x C-s +@findex save-buffer + When you wish to save the file and make your changes permanent, type +@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} +displays a message like this: + +@example +Wrote /u/rms/gnu/gnu.tasks +@end example + +@noindent +If the selected buffer is not modified (no changes have been made in it +since the buffer was created or last saved), saving is not really done, +because it would have no effect. Instead, @kbd{C-x C-s} displays a message +like this in the echo area: + +@example +(No changes need to be saved) +@end example + +@kindex C-x s +@findex save-some-buffers + The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any +or all modified buffers. It asks you what to do with each buffer. The +possible responses are analogous to those of @code{query-replace}: + +@table @kbd +@item y +Save this buffer and ask about the rest of the buffers. +@item n +Don't save this buffer, but ask about the rest of the buffers. +@item ! +Save this buffer and all the rest with no more questions. +@c following generates acceptable underfull hbox +@item @key{RET} +Terminate @code{save-some-buffers} without any more saving. +@item . +Save this buffer, then exit @code{save-some-buffers} without even asking +about other buffers. +@item C-r +View the buffer that you are currently being asked about. When you exit +View mode, you get back to @code{save-some-buffers}, which asks the +question again. +@item C-h +Display a help message about these options. +@end table + + @kbd{C-x C-c}, the key sequence to exit Emacs, invokes +@code{save-some-buffers} and therefore asks the same questions. + +@kindex M-~ +@findex not-modified + If you have changed a buffer but you do not want to save the changes, +you should take some action to prevent it. Otherwise, each time you use +@kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by +mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}), +which clears out the indication that the buffer is modified. If you do +this, none of the save commands will believe that the buffer needs to be +saved. (@samp{~} is often used as a mathematical symbol for `not'; thus +@kbd{M-~} is `not', metafied.) You could also use +@code{set-visited-file-name} (see below) to mark the buffer as visiting +a different file name, one which is not in use for anything important. +Alternatively, you can cancel all the changes made since the file was +visited or saved, by reading the text from the file again. This is +called @dfn{reverting}. @xref{Reverting}. You could also undo all the +changes by repeating the undo command @kbd{C-x u} until you have undone +all the changes; but reverting is easier. + +@findex set-visited-file-name + @kbd{M-x set-visited-file-name} alters the name of the file that the +current buffer is visiting. It reads the new file name using the +minibuffer. Then it specifies the visited file name and changes the +buffer name correspondingly (as long as the new name is not in use). +@code{set-visited-file-name} does not save the buffer in the newly +visited file; it just alters the records inside Emacs in case you do +save later. It also marks the buffer as ``modified'' so that @kbd{C-x +C-s} in that buffer @emph{will} save. + +@kindex C-x C-w +@findex write-file + If you wish to mark the buffer as visiting a different file and save it +right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely +equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}. +@kbd{C-x C-s} used on a buffer that is not visiting a file has the +same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the +buffer as visiting that file, and saves it there. The default file name in +a buffer that is not visiting a file is made by combining the buffer name +with the buffer's default directory. + + If the new file name implies a major mode, then @kbd{C-x C-w} switches +to that major mode, in most cases. The command +@code{set-visited-file-name} also does this. @xref{Choosing Modes}. + + If Emacs is about to save a file and sees that the date of the latest +version on disk does not match what Emacs last read or wrote, Emacs +notifies you of this fact, because it probably indicates a problem caused +by simultaneous editing and requires your immediate attention. +@xref{Interlocking,, Simultaneous Editing}. + +@vindex require-final-newline + If the variable @code{require-final-newline} is non-@code{nil}, Emacs +puts a newline at the end of any file that doesn't already end in one, +every time a file is saved or written. The default is @code{nil}. + +@menu +* Backup:: How Emacs saves the old version of your file. +* Interlocking:: How Emacs protects against simultaneous editing + of one file by two users. +@end menu + +@node Backup +@subsection Backup Files +@cindex backup file +@vindex make-backup-files +@vindex vc-make-backup-files +@vindex backup-enable-predicate + + On most operating systems, rewriting a file automatically destroys all +record of what the file used to contain. Thus, saving a file from Emacs +throws away the old contents of the file---or it would, except that +Emacs carefully copies the old contents to another file, called the +@dfn{backup} file, before actually saving. + + For most files, the variable @code{make-backup-files} determines +whether to make backup files. On most operating systems, its default +value is @code{t}, so that Emacs does write backup files. + + For files managed by a version control system (@pxref{Version +Control}), the variable @code{vc-make-backup-files} determines whether +to make backup files. By default, it is @code{nil}, since backup files +are redundant when you store all the previous versions in a version +control system. @xref{VC Workfile Handling}. + + The default value of the @code{backup-enable-predicate} variable +prevents backup files being written for files in @file{/tmp}. + + At your option, Emacs can keep either a single backup file or a series of +numbered backup files for each file that you edit. + + Emacs makes a backup for a file only the first time the file is saved +from one buffer. No matter how many times you save a file, its backup file +continues to contain the contents from before the file was visited. +Normally this means that the backup file contains the contents from before +the current editing session; however, if you kill the buffer and then visit +the file again, a new backup file will be made by the next save. + + You can also explicitly request making another backup file from a +buffer even though it has already been saved at least once. If you save +the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made +into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s} +saves the buffer, but first makes the previous file contents into a new +backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a +backup from the previous contents, and arranges to make another from the +newly saved contents, if you save again. + +@menu +* Names: Backup Names. How backup files are named; + choosing single or numbered backup files. +* Deletion: Backup Deletion. Emacs deletes excess numbered backups. +* Copying: Backup Copying. Backups can be made by copying or renaming. +@end menu + +@node Backup Names +@subsubsection Single or Numbered Backups + + If you choose to have a single backup file (this is the default), +the backup file's name is constructed by appending @samp{~} to the +file name being edited; thus, the backup file for @file{eval.c} would +be @file{eval.c~}. + + If you choose to have a series of numbered backup files, backup file +names are made by appending @samp{.~}, the number, and another @samp{~} to +the original file name. Thus, the backup files of @file{eval.c} would be +called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names +like @file{eval.c.~259~} and beyond. + + If protection stops you from writing backup files under the usual names, +the backup file is written as @file{%backup%~} in your home directory. +Only one such file can exist, so only the most recently made such backup is +available. + +@vindex version-control + The choice of single backup or numbered backups is controlled by the +variable @code{version-control}. Its possible values are + +@table @code +@item t +Make numbered backups. +@item nil +Make numbered backups for files that have numbered backups already. +Otherwise, make single backups. +@item never +Do not in any case make numbered backups; always make single backups. +@end table + +@noindent +You can set @code{version-control} locally in an individual buffer to +control the making of backups for that buffer's file. For example, +Rmail mode locally sets @code{version-control} to @code{never} to make sure +that there is only one backup for an Rmail file. @xref{Locals}. + +@cindex @code{VERSION_CONTROL} environment variable + If you set the environment variable @code{VERSION_CONTROL}, to tell +various GNU utilities what to do with backup files, Emacs also obeys the +environment variable by setting the Lisp variable @code{version-control} +accordingly at startup. If the environment variable's value is @samp{t} +or @samp{numbered}, then @code{version-control} becomes @code{t}; if the +value is @samp{nil} or @samp{existing}, then @code{version-control} +becomes @code{nil}; if it is @samp{never} or @samp{simple}, then +@code{version-control} becomes @code{never}. + +@node Backup Deletion +@subsubsection Automatic Deletion of Backups + + To prevent unlimited consumption of disk space, Emacs can delete numbered +backup versions automatically. Generally Emacs keeps the first few backups +and the latest few backups, deleting any in between. This happens every +time a new backup is made. + +@vindex kept-old-versions +@vindex kept-new-versions + The two variables @code{kept-old-versions} and +@code{kept-new-versions} control this deletion. Their values are, +respectively the number of oldest (lowest-numbered) backups to keep and +the number of newest (highest-numbered) ones to keep, each time a new +backup is made. Recall that these values are used just after a new +backup version is made; that newly made backup is included in the count +in @code{kept-new-versions}. By default, both variables are 2. + +@vindex delete-old-versions + If @code{delete-old-versions} is non-@code{nil}, the excess +middle versions are deleted without a murmur. If it is @code{nil}, the +default, then you are asked whether the excess middle versions should +really be deleted. + + Dired's @kbd{.} (Period) command can also be used to delete old versions. +@xref{Dired Deletion}. + +@node Backup Copying +@subsubsection Copying vs.@: Renaming + + Backup files can be made by copying the old file or by renaming it. This +makes a difference when the old file has multiple names. If the old file +is renamed into the backup file, then the alternate names become names for +the backup file. If the old file is copied instead, then the alternate +names remain names for the file that you are editing, and the contents +accessed by those names will be the new contents. + + The method of making a backup file may also affect the file's owner +and group. If copying is used, these do not change. If renaming is used, +you become the file's owner, and the file's group becomes the default +(different operating systems have different defaults for the group). + + Having the owner change is usually a good idea, because then the owner +always shows who last edited the file. Also, the owners of the backups +show who produced those versions. Occasionally there is a file whose +owner should not change; it is a good idea for such files to contain +local variable lists to set @code{backup-by-copying-when-mismatch} +locally (@pxref{File Variables}). + +@vindex backup-by-copying +@vindex backup-by-copying-when-linked +@vindex backup-by-copying-when-mismatch + The choice of renaming or copying is controlled by three variables. +Renaming is the default choice. If the variable +@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, +if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, +then copying is used for files that have multiple names, but renaming +may still be used when the file being edited has only one name. If the +variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then +copying is used if renaming would cause the file's owner or group to +change. @code{backup-by-copying-when-mismatch} is @code{t} by default +if you start Emacs as the superuser. + + When a file is managed with a version control system (@pxref{Version +Control}), Emacs does not normally make backups in the usual way for +that file. But check-in and check-out are similar in some ways to +making backups. One unfortunate similarity is that these operations +typically break hard links, disconnecting the file name you visited from +any alternate names for the same file. This has nothing to do with +Emacs---the version control system does it. + +@node Interlocking +@subsection Protection against Simultaneous Editing + +@cindex file dates +@cindex simultaneous editing + Simultaneous editing occurs when two users visit the same file, both +make changes, and then both save them. If nobody were informed that +this was happening, whichever user saved first would later find that his +changes were lost. + + On some systems, Emacs notices immediately when the second user starts +to change the file, and issues an immediate warning. On all systems, +Emacs checks when you save the file, and warns if you are about to +overwrite another user's changes. You can prevent loss of the other +user's work by taking the proper corrective action instead of saving the +file. + +@findex ask-user-about-lock +@cindex locking files + When you make the first modification in an Emacs buffer that is +visiting a file, Emacs records that the file is @dfn{locked} by you. +(It does this by creating a symbolic link in the same directory with a +different name.) Emacs removes the lock when you save the changes. The +idea is that the file is locked whenever an Emacs buffer visiting it has +unsaved changes. + +@cindex collision + If you begin to modify the buffer while the visited file is locked by +someone else, this constitutes a @dfn{collision}. When Emacs detects a +collision, it asks you what to do, by calling the Lisp function +@code{ask-user-about-lock}. You can redefine this function for the sake +of customization. The standard definition of this function asks you a +question and accepts three possible answers: + +@table @kbd +@item s +Steal the lock. Whoever was already changing the file loses the lock, +and you gain the lock. +@item p +Proceed. Go ahead and edit the file despite its being locked by someone else. +@item q +Quit. This causes an error (@code{file-locked}) and the modification you +were trying to make in the buffer does not actually take place. +@end table + + Note that locking works on the basis of a file name; if a file has +multiple names, Emacs does not realize that the two names are the same file +and cannot prevent two users from editing it simultaneously under different +names. However, basing locking on names means that Emacs can interlock the +editing of new files that will not really exist until they are saved. + + Some systems are not configured to allow Emacs to make locks, and +there are cases where lock files cannot be written. In these cases, +Emacs cannot detect trouble in advance, but it still can detect the +collision when you try to save a file and overwrite someone else's +changes. + + If Emacs or the operating system crashes, this may leave behind lock +files which are stale. So you may occasionally get warnings about +spurious collisions. When you determine that the collision is spurious, +just use @kbd{p} to tell Emacs to go ahead anyway. + + Every time Emacs saves a buffer, it first checks the last-modification +date of the existing file on disk to verify that it has not changed since the +file was last visited or saved. If the date does not match, it implies +that changes were made in the file in some other way, and these changes are +about to be lost if Emacs actually does save. To prevent this, Emacs +prints a warning message and asks for confirmation before saving. +Occasionally you will know why the file was changed and know that it does +not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should +cancel the save with @kbd{C-g} and investigate the situation. + + The first thing you should do when notified that simultaneous editing +has already taken place is to list the directory with @kbd{C-u C-x C-d} +(@pxref{Directories}). This shows the file's current author. You +should attempt to contact him to warn him not to continue editing. +Often the next step is to save the contents of your Emacs buffer under a +different name, and use @code{diff} to compare the two files.@refill + +@node Reverting +@section Reverting a Buffer +@findex revert-buffer +@cindex drastic changes + + If you have made extensive changes to a file and then change your mind +about them, you can get rid of them by reading in the previous version +of the file. To do this, use @kbd{M-x revert-buffer}, which operates on +the current buffer. Since reverting a buffer unintentionally could lose +a lot of work, you must confirm this command with @kbd{yes}. + + @code{revert-buffer} keeps point at the same distance (measured in +characters) from the beginning of the file. If the file was edited only +slightly, you will be at approximately the same piece of text after +reverting as before. If you have made drastic changes, the same value of +point in the old file may address a totally different piece of text. + + Reverting marks the buffer as ``not modified'' until another change is +made. + + Some kinds of buffers whose contents reflect data bases other than files, +such as Dired buffers, can also be reverted. For them, reverting means +recalculating their contents from the appropriate data base. Buffers +created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer} +reports an error when asked to do so. + +@vindex revert-without-query + When you edit a file that changes automatically and frequently---for +example, a log of output from a process that continues to run---it may be +useful for Emacs to revert the file without querying you, whenever you +visit the file again with @kbd{C-x C-f}. + + To request this behavior, set the variable @code{revert-without-query} +to a list of regular expressions. When a file name matches one of these +regular expressions, @code{find-file} and @code{revert-buffer} will +revert it automatically if it has changed---provided the buffer itself +is not modified. (If you have edited the text, it would be wrong to +discard your changes.) + +@node Auto Save +@section Auto-Saving: Protection Against Disasters +@cindex Auto Save mode +@cindex mode, Auto Save +@cindex crashes + + Emacs saves all the visited files from time to time (based on counting +your keystrokes) without being asked. This is called @dfn{auto-saving}. +It prevents you from losing more than a limited amount of work if the +system crashes. + + When Emacs determines that it is time for auto-saving, each buffer is +considered, and is auto-saved if auto-saving is turned on for it and it +has been changed since the last time it was auto-saved. The message +@samp{Auto-saving...} is displayed in the echo area during auto-saving, +if any files are actually auto-saved. Errors occurring during +auto-saving are caught so that they do not interfere with the execution +of commands you have been typing. + +@menu +* Files: Auto Save Files. The file where auto-saved changes are + actually made until you save the file. +* Control: Auto Save Control. Controlling when and how often to auto-save. +* Recover:: Recovering text from auto-save files. +@end menu + +@node Auto Save Files +@subsection Auto-Save Files + + Auto-saving does not normally save in the files that you visited, because +it can be very undesirable to save a program that is in an inconsistent +state when you have made half of a planned change. Instead, auto-saving +is done in a different file called the @dfn{auto-save file}, and the +visited file is changed only when you request saving explicitly (such as +with @kbd{C-x C-s}). + + Normally, the auto-save file name is made by appending @samp{#} to the +front and rear of the visited file name. Thus, a buffer visiting file +@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that +are not visiting files are auto-saved only if you request it explicitly; +when they are auto-saved, the auto-save file name is made by appending +@samp{#%} to the front and @samp{#} to the rear of buffer name. For +example, the @samp{*mail*} buffer in which you compose messages to be +sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file +names are made this way unless you reprogram parts of Emacs to do +something different (the functions @code{make-auto-save-file-name} and +@code{auto-save-file-name-p}). The file name to be used for auto-saving +in a buffer is calculated when auto-saving is turned on in that buffer. + + When you delete a substantial part of the text in a large buffer, auto +save turns off temporarily in that buffer. This is because if you +deleted the text unintentionally, you might find the auto-save file more +useful if it contains the deleted text. To reenable auto-saving after +this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x +auto-save}. + +@vindex auto-save-visited-file-name + If you want auto-saving to be done in the visited file, set the variable +@code{auto-save-visited-file-name} to be non-@code{nil}. In this mode, +there is really no difference between auto-saving and explicit saving. + +@vindex delete-auto-save-files + A buffer's auto-save file is deleted when you save the buffer in its +visited file. To inhibit this, set the variable @code{delete-auto-save-files} +to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or +@code{set-visited-file-name} renames any auto-save file to go with +the new visited name. + +@node Auto Save Control +@subsection Controlling Auto-Saving + +@vindex auto-save-default +@findex auto-save-mode + Each time you visit a file, auto-saving is turned on for that file's +buffer if the variable @code{auto-save-default} is non-@code{nil} (but not +in batch mode; @pxref{Entering Emacs}). The default for this variable is +@code{t}, so auto-saving is the usual practice for file-visiting buffers. +Auto-saving can be turned on or off for any existing buffer with the +command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x +auto-save-mode} turns auto-saving on with a positive argument, off with a +zero or negative argument; with no argument, it toggles. + +@vindex auto-save-interval + Emacs does auto-saving periodically based on counting how many characters +you have typed since the last time auto-saving was done. The variable +@code{auto-save-interval} specifies how many characters there are between +auto-saves. By default, it is 300. + +@vindex auto-save-timeout + Auto-saving also takes place when you stop typing for a while. The +variable @code{auto-save-timeout} says how many seconds Emacs should +wait before it does an auto save (and perhaps also a garbage +collection). (The actual time period is longer if the current buffer is +long; this is a heuristic which aims to keep out of your way when you +are editing long buffers, in which auto-save takes an appreciable amount +of time.) Auto-saving during idle periods accomplishes two things: +first, it makes sure all your work is saved if you go away from the +terminal for a while; second, it may avoid some auto-saving while you +are actually typing. + + Emacs also does auto-saving whenever it gets a fatal error. This +includes killing the Emacs job with a shell command such as @samp{kill +%emacs}, or disconnecting a phone line or network connection. + +@findex do-auto-save + You can request an auto-save explicitly with the command @kbd{M-x +do-auto-save}. + +@node Recover +@subsection Recovering Data from Auto-Saves + +@findex recover-file + You can use the contents of an auto-save file to recover from a loss +of data with the command @kbd{M-x recover-file @key{RET} @var{file} +@key{RET}}. This visits @var{file} and then (after your confirmation) +restores the contents from its auto-save file @file{#@var{file}#}. +You can then save with @kbd{C-x C-s} to put the recovered text into +@var{file} itself. For example, to recover file @file{foo.c} from its +auto-save file @file{#foo.c#}, do:@refill + +@example +M-x recover-file @key{RET} foo.c @key{RET} +yes @key{RET} +C-x C-s +@end example + + Before asking for confirmation, @kbd{M-x recover-file} displays a +directory listing describing the specified file and the auto-save file, +so you can compare their sizes and dates. If the auto-save file +is older, @kbd{M-x recover-file} does not offer to read it. + +@findex recover-session + If Emacs or the computer crashes, you can recover all the files you +were editing from their auto save files with the command @kbd{M-x +recover-session}. This first shows you a list of recorded interrupted +sessions. Move point to the one you choose, and type @kbd{C-c C-c}. + + Then @code{recover-session} asks about each of the files that were +being edited during that session, asking whether to recover that file. +If you answer @kbd{y}, it calls @code{recover-file}, which works in its +normal fashion. It shows the dates of the original file and its +auto-save file, and asks once again whether to recover that file. + + When @code{recover-session} is done, the files you've chosen to +recover are present in Emacs buffers. You should then save them. Only +this---saving them---updates the files themselves. + +@vindex auto-save-list-file-prefix + Interrupted sessions are recorded for later recovery in files named +@file{~/.saves-@var{pid}-@var{hostname}}. The @samp{~/.saves} portion of +these names comes from the value of @code{auto-save-list-file-prefix}. +You can arrange to record sessions in a different place by setting that +variable in your @file{.emacs} file, but you'll have to redefine +@code{recover-session} as well to make it look in the new place. If you +set @code{auto-save-list-file-prefix} to @code{nil} in your +@file{.emacs} file, sessions are not recorded for recovery. + +@node File Aliases +@section File Name Aliases + + Symbolic links and hard links both make it possible for several file +names to refer to the same file. Hard links are alternate names that +refer directly to the file; all the names are equally valid, and no one +of them is preferred. By contrast, a symbolic link is a kind of defined +alias: when @file{foo} is a symbolic link to @file{bar}, you can use +either name to refer to the file, but @file{bar} is the real name, while +@file{foo} is just an alias. More complex cases occur when symbolic +links point to directories. + + If you visit two names for the same file, normally Emacs makes +two different buffers, but it warns you about the situation. + +@vindex find-file-existing-other-name + If you wish to avoid visiting the same file in two buffers under +different names, set the variable @code{find-file-existing-other-name} +to a non-@code{nil} value. Then @code{find-file} uses the existing +buffer visiting the file, no matter which of the file's names you +specify. + +@vindex find-file-visit-truename +@cindex truenames of files +@cindex file truenames + If the variable @code{find-file-visit-truename} is non-@code{nil}, +then the file name recorded for a buffer is the file's @dfn{truename} +(made by replacing all symbolic links with their target names), rather +than the name you specify. Setting @code{find-file-visit-truename} also +implies the effect of @code{find-file-existing-other-name}. + +@node Version Control +@section Version Control +@cindex version control + + @dfn{Version control systems} are packages that can record multiple +versions of a source file, usually storing the unchanged parts of the +file just once. Version control systems also record history information +such as the creation time of each version, who created it, and a +description of what was changed in that version. + + The Emacs version control interface is called VC. Its commands work +with three version control systems---RCS, CVS and SCCS. The GNU project +recommends RCS and CVS, which are free software and available from the +Free Software Foundation. + +@menu +* Introduction to VC:: How version control works in general. +* VC Mode Line:: How the mode line shows version control status. +* Basic VC Editing:: How to edit a file under version control. +* Old Versions:: Examining and comparing old versions. +* Secondary VC Commands:: The commands used a little less frequently. +* Branches:: Multiple lines of development. +* Snapshots:: Sets of file versions treated as a unit. +* Miscellaneous VC:: Various other commands and features of VC. +* Customizing VC:: Variables that change VC's behavior. +@end menu + +@node Introduction to VC +@subsection Introduction to Version Control + + VC allows you to use a version control system from within Emacs, +integrating the version control operations smoothly with editing. VC +provides a uniform interface to version control, so that regardless of +which version control system is in use, you can use it the same way. + + This section provides a general overview of version control, and +describes the version control systems that VC supports. You can skip +this section if you are already familiar with the version control system +you want to use. + +@menu +* Version Systems:: Supported version control back-end systems. +* VC Concepts:: Words and concepts related to version control. +@end menu + +@node Version Systems +@subsubsection Supported Version Control Systems + +@cindex RCS +@cindex back end (version control) + VC currently works with three different version control systems or +``back ends'': RCS, CVS, and SCCS. + + RCS is a free version control system that is available from the Free +Software Foundation. It is perhaps the most mature of the supported +back ends, and the VC commands are conceptually closest to RCS. Almost +everything you can do with RCS can be done through VC. + +@cindex CVS + CVS is built on top of RCS, and extends the features of RCS, allowing +for more sophisticated release management, and concurrent multi-user +development. VC supports basic editing operations under CVS, but for +some less common tasks you still need to call CVS from the command line. +Note also that before using CVS you must set up a repository, which is a +subject too complex to treat here. + +@cindex SCCS + SCCS is a proprietary but widely used version control system. In +terms of capabilities, it is the weakest of the three that VC +supports. VC compensates for certain features missing in SCCS +(snapshots, for example) by implementing them itself, but some other VC +features, such as multiple branches, are not available with SCCS. You +should use SCCS only if for some reason you cannot use RCS. + +@node VC Concepts +@subsubsection Concepts of Version Control + +@cindex master file +@cindex registered file + When a file is under version control, we also say that it is +@dfn{registered} in the version control system. Each registered file +has a corresponding @dfn{master file} which represents the file's +present state plus its change history---enough to reconstruct the +current version or any earlier version. Usually the master file also +records a @dfn{log entry} for each version, describing in words what was +changed in that version. + +@cindex work file +@cindex checking out files + The file that is maintained under version control is sometimes called +the @dfn{work file} corresponding to its master file. You edit the work +file and make changes in it, as you would with an ordinary file. (With +SCCS and RCS, you must @dfn{lock} the file before you start to edit it.) +After you are done with a set of changes, you @dfn{check the file in}, +which records the changes in the master file, along with a log entry for +them. + + With CVS, there are usually multiple work files corresponding to a +single master file---often each user has his own copy. It is also +possible to use RCS in this way, but this is not the usual way to use +RCS. + +@cindex locking and version control + A version control system typically has some mechanism to coordinate +between users who want to change the same file. One method is +@dfn{locking} (analogous to the locking that Emacs uses to detect +simultaneous editing of a file, but distinct from it). The other method +is to merge your changes with other people's changes when you check them +in. + + With version control locking, work files are normally read-only so +that you cannot change them. You ask the version control system to make +a work file writable for you by locking it; only one user can do +this at any given time. When you check in your changes, that unlocks +the file, making the work file read-only again. This allows other users +to lock the file to make further changes. SCCS always uses locking, and +RCS normally does. + + The other alternative for RCS is to let each user modify the work file +at any time. In this mode, locking is not required, but it is +permitted; check-in is still the way to record a new version. + + CVS normally allows each user to modify his own copy of the work file +at any time, but requires merging with changes from other users at +check-in time. However, CVS can also be set up to require locking. +(@pxref{Backend Options}). + +@node VC Mode Line +@subsection Version Control and the Mode Line + + When you visit a file that is under version control, Emacs indicates +this on the mode line. For example, @samp{RCS-1.3} says that RCS is +used for that file, and the current version is 1.3. + + The character between the back-end name and the version number +indicates the version control status of the file. @samp{-} means that +the work file is not locked (if locking is in use), or not modified (if +locking is not in use). @samp{:} indicates that the file is locked, or +that it is modified. If the file is locked by some other user (for +instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. + +@node Basic VC Editing +@subsection Basic Editing under Version Control + + The principal VC command is an all-purpose command that performs +either locking or check-in, depending on the situation. + +@table @kbd +@item C-x C-q +@itemx C-x v v +Perform the next logical version control operation on this file. +@end table + +@findex vc-next-action +@findex vc-toggle-read-only +@kindex C-x v v +@kindex C-x C-q @r{(Version Control)} + Strictly speaking, the command for this job is @code{vc-next-action}, +bound to @kbd{C-x v v}. However, the normal meaning of @kbd{C-x C-q} is +to make a read-only buffer writable, or vice versa; we have extended it +to do the same job properly for files managed by version control, by +performing the appropriate version control operations. When you type +@kbd{C-x C-q} on a registered file, it acts like @kbd{C-x v v}. + + The precise action of this command depends on the state of the file, +and whether the version control system uses locking or not. SCCS and +RCS normally use locking; CVS normally does not use locking. + +@menu +* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. +* Without Locking:: Without locking: default mode for CVS. +* Log Buffer:: Features available in log entry buffers. +@end menu + +@node VC with Locking +@subsubsection Basic Version Control with Locking + + If locking is used for the file (as with SCCS, and RCS in its default +mode), @kbd{C-x C-q} can either lock a file or check it in: + +@itemize @bullet +@item +If the file is not locked, @kbd{C-x C-q} locks it, and +makes it writable so that you can change it. + +@item +If the file is locked by you, and contains changes, @kbd{C-x C-q} checks +in the changes. In order to do this, it first reads the log entry +for the new version. @xref{Log Buffer}. + +@item +If the file is locked by you, but you have not changed it since you +locked it, @kbd{C-x C-q} releases the lock and makes the file read-only +again. + +@item +If the file is locked by some other user, @kbd{C-x C-q} asks you whether +you want to ``steal the lock'' from that user. If you say yes, the file +becomes locked by you, but a message is sent to the person who had +formerly locked the file, to inform him of what has happened. +@end itemize + + These rules also apply when you use CVS in locking mode, except +that there is no such thing as stealing a lock. + +@node Without Locking +@subsubsection Basic Version Control without Locking + + When there is no locking---the default for CVS---work files are always +writable; you do not need to do anything before you begin to edit a +file. The status indicator on the mode line is @samp{-} if the file is +unmodified; it flips to @samp{:} as soon as you save any changes in the +work file. + + Here is what @kbd{C-x C-q} does when using CVS: + +@itemize @bullet +@item +If some other user has checked in changes into the master file, +Emacs asks you whether you want to merge those changes into your own +work file (@pxref{Merging}). You must do this before you can check in +your own changes. + +@item +If there are no new changes in the master file, but you have made +modifications in your work file, @kbd{C-x C-q} checks in your changes. +In order to do this, it first reads the log entry for the new version. +@xref{Log Buffer}. + +@item +If the file is not modified, the @kbd{C-x C-q} does nothing. +@end itemize + + These rules also apply when you use RCS in the mode that does not +require locking, except that automatic merging of changes from the +master file is not implemented. Unfortunately, this means that nothing +informs you if another user has checked in changes in the same file +since you began editing it, and when this happens, his changes will be +effectively removed when you check in your version (though they will +remain in the master file, so they will not be entirely lost). You must +therefore verify the current version is unchanged, before you check in your +changes. We hope to eliminate this risk and provide automatic merging +with RCS in a future Emacs version. + + In addition, locking is possible with RCS even in this mode, although +it is not required; @kbd{C-x C-q} with an unmodified file locks the +file, just as it does with RCS in its normal (locking) mode. + +@node Log Buffer +@subsubsection Features of the Log Entry Buffer + + When you check in changes, @kbd{C-x C-q} first reads a log entry. It +pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. +When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer. +That is when check-in really happens. + + To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that +buffer. You can switch buffers and do other editing. As long as you +don't try to check in another file, the entry you were editing remains +in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any +time to complete the check-in. + + If you change several source files for the same reason, it is often +convenient to specify the same log entry for many of the files. To do +this, use the history of previous log entries. The commands @kbd{M-n}, +@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the +minibuffer history commands (except that these versions are used outside +the minibuffer). + +@vindex vc-log-mode-hook + Each time you check in a file, the log entry buffer is put into VC Log +mode, which involves running two hooks: @code{text-mode-hook} and +@code{vc-log-mode-hook}. @xref{Hooks}. + +@node Old Versions +@subsection Examining And Comparing Old Versions + + One of the convenient features of version control is the ability +to examine any version of a file, or compare two versions. + +@table @kbd +@item C-x v ~ @var{version} @key{RET} +Examine version @var{version} of the visited file, in a buffer of its +own. + +@item C-x v = +Compare the current buffer contents with the latest checked-in version +of the file. + +@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} +Compare the specified two versions of @var{file}. + +@item C-x v g +Display the result of the CVS annotate command using colors. +@end table + +@findex vc-version-other-window +@kindex C-x v ~ + To examine an old version in toto, visit the file and then type +@kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}). +This puts the text of version @var{version} in a file named +@file{@var{filename}.~@var{version}~}, and visits it in its own buffer +in a separate window. (In RCS, you can also select an old version +and create a branch from it. @xref{Branches}.) + +@findex vc-diff +@kindex C-x v = + But usually it is more convenient to compare two versions of the file, +with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =} +compares the current buffer contents (saving them in the file if +necessary) with the last checked-in version of the file. @kbd{C-u C-x v +=}, with a numeric argument, reads a file name and two version numbers, +then compares those versions of the specified file. + + If you supply a directory name instead of the name of a registered +file, this command compares the two specified versions of all registered +files in that directory and its subdirectories. + + You can specify a checked-in version by its number; an empty input +specifies the current contents of the work file (which may be different +from all the checked-in versions). You can also specify a snapshot name +(@pxref{Snapshots}) instead of one or both version numbers. + + This command works by running the @code{diff} utility, getting the +options from the variable @code{diff-switches}. It displays the output +in a special buffer in another window. Unlike the @kbd{M-x diff} +command, @kbd{C-x v =} does not try to locate the changes in the old and +new versions. This is because normally one or both versions do not +exist as files when you compare them; they exist only in the records of +the master file. @xref{Comparing Files}, for more information about +@kbd{M-x diff}. + +@findex vc-annotate +@kindex C-x v g + For CVS-controlled files, you can display the result of the CVS +annotate command, using colors to enhance the visual appearance. Use +the command @kbd{M-x vc-annotate} to do this. Red means new, blue means +old, and intermediate colors indicate intermediate ages. A prefix +argument @var{n} specifies a stretch factor for the time scale; it makes +each color cover a period @var{n} times as long. + +@node Secondary VC Commands +@subsection The Secondary Commands of VC + + This section explains the secondary commands of VC; those that you might +use once a day. + +@menu +* Registering:: Putting a file under version control. +* VC Status:: Viewing the VC status of files. +* VC Undo:: Cancelling changes before or after check-in. +* VC Dired Mode:: Listing files managed by version control. +* VC Dired Commands:: Commands to use in a VC Dired buffer. +@end menu + +@node Registering +@subsubsection Registering a File for Version Control + +@kindex C-x v i +@findex vc-register + You can put any file under version control by simply visiting it, and +then typing @w{@kbd{C-x v i}} (@code{vc-register}). + +@table @kbd +@item C-x v i +Register the visited file for version control. +@end table + +@vindex vc-default-back-end + To register the file, Emacs must choose which version control system +to use for it. You can specify your choice explicitly by setting +@code{vc-default-back-end} to @code{RCS}, @code{CVS} or @code{SCCS}. +Otherwise, if there is a subdirectory named @file{RCS}, @file{SCCS}, or +@file{CVS}, Emacs uses the corresponding version control system. In the +absence of any specification, the default choice is RCS if RCS is +installed, otherwise SCCS. + + If locking is in use, @kbd{C-x v i} leaves the file unlocked and +read-only. Type @kbd{C-x C-q} if you wish to start editing it. After +registering a file with CVS, you must subsequently commit the initial +version by typing @kbd{C-x C-q}. + +@vindex vc-default-init-version + The initial version number for a newly registered file is 1.1, by +default. You can specify a different default by setting the variable +@code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric +argument; then it reads the initial version number for this particular +file using the minibuffer. + +@vindex vc-initial-comment + If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an +initial comment to describe the purpose of this source file. Reading +the initial comment works like reading a log entry (@pxref{Log Buffer}). + +@node VC Status +@subsubsection VC Status Commands + +@table @kbd +@item C-x v l +Display version control state and change history. +@end table + +@kindex C-x v l +@findex vc-print-log + To view the detailed version control status and history of a file, +type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of +changes to the current file, including the text of the log entries. The +output appears in a separate window. + +@node VC Undo +@subsubsection Undoing Version Control Actions + +@table @kbd +@item C-x v u +Revert the buffer and the file to the last checked-in version. + +@item C-x v c +Remove the last-entered change from the master for the visited file. +This undoes your last check-in. +@end table + +@kindex C-x v u +@findex vc-revert-buffer + If you want to discard your current set of changes and revert to the +last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}). +This leaves the file unlocked; if locking is in use, you must first lock +the file again before you change it again. @kbd{C-x v u} requires +confirmation, unless it sees that you haven't made any changes since the +last checked-in version. + + @kbd{C-x v u} is also the command to unlock a file if you lock it and +then decide not to change it. + +@kindex C-x v c +@findex vc-cancel-version + To cancel a change that you already checked in, use @kbd{C-x v c} +(@code{vc-cancel-version}). This command discards all record of the +most recent checked-in version. @kbd{C-x v c} also offers to revert +your work file and buffer to the previous version (the one that precedes +the version that is deleted). + + If you answer @kbd{no}, VC keeps your changes in the buffer, and locks +the file. The no-revert option is useful when you have checked in a +change and then discover a trivial error in it; you can cancel the +erroneous check-in, fix the error, and check the file in again. + + When @kbd{C-x v c} does not revert the buffer, it unexpands all +version control headers in the buffer instead (@pxref{Version Headers}). +This is because the buffer no longer corresponds to any existing +version. If you check it in again, the check-in process will expand the +headers properly for the new version number. + + However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header +automatically. If you use that header feature, you have to unexpand it +by hand---by deleting the entry for the version that you just canceled. + + Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of +work with it. To help you be careful, this command always requires +confirmation with @kbd{yes}. Note also that this command is disabled +under CVS, because canceling versions is very dangerous and discouraged +with CVS. + +@node VC Dired Mode +@subsubsection Dired under VC + +@kindex C-x v d +@findex vc-directory + When you are working on a large program, it is often useful to find +out which files have changed within an entire directory tree, or to view +the status of all files under version control at once, and to perform +version control operations on collections of files. You can use the +command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing +that includes only files relevant for version control. + +@vindex vc-dired-terse-display + @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks +much like an ordinary Dired buffer (@pxref{Dired}); however, normally it +shows only the noteworthy files (those locked or not up-to-date). This +is called @dfn{terse display}. If you set the variable +@code{vc-dired-terse-display} to @code{nil}, then VC Dired shows all +relevant files---those managed under version control, plus all +subdirectories (@dfn{full display}). The command @kbd{v t} in a VC +Dired buffer toggles between terse display and full display (@pxref{VC +Dired Commands}). + +@vindex vc-dired-recurse + By default, VC Dired produces a recursive listing of noteworthy or +relevant files at or below the given directory. You can change this by +setting the variable @code{vc-dired-recurse} to @code{nil}; then VC +Dired shows only the files in the given directory. + + The line for an individual file shows the version control state in the +place of the hard link count, owner, group, and size of the file. If +the file is unmodified, in sync with the master file, the version +control state shown is blank. Otherwise it consists of text in +parentheses. Under RCS and SCCS, the name of the user locking the file +is shown; under CVS, an abbreviated version of the @samp{cvs status} +output is used. Here is an example using RCS: + +@smallexample +@group + /home/jim/project: + + -rw-r--r-- (jim) Apr 2 23:39 file1 + -r--r--r-- Apr 5 20:21 file2 +@end group +@end smallexample + +@noindent +The files @samp{file1} and @samp{file2} are under version control, +@samp{file1} is locked by user jim, and @samp{file2} is unlocked. + + Here is an example using CVS: + +@smallexample +@group + /home/joe/develop: + + -rw-r--r-- (modified) Aug 2 1997 file1.c + -rw-r--r-- Apr 4 20:09 file2.c + -rw-r--r-- (merge) Sep 13 1996 file3.c +@end group +@end smallexample + + Here @samp{file1.c} is modified with respect to the repository, and +@samp{file2.c} is not. @samp{file3.c} is modified, but other changes +have also been checked in to the repository---you need to merge them +with the work file before you can check it in. + +@vindex vc-directory-exclusion-list + When VC Dired displays subdirectories (in the ``full'' display mode), +it omits some that should never contain any files under version control. +By default, this includes Version Control subdirectories such as +@samp{RCS} and @samp{CVS}; you can customize this by setting the +variable @code{vc-directory-exclusion-list}. + + You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in +ordinary Dired, that allows you to specify additional switches for the +@samp{ls} command. + +@node VC Dired Commands +@subsubsection VC Dired Commands + + All the usual Dired commands work normally in VC Dired mode, except +for @kbd{v}, which is redefined as the version control prefix. You can +invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by +typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply +to the file name on the current line. + + The command @kbd{v v} (@code{vc-next-action}) operates on all the +marked files, so that you can lock or check in several files at once. +If it operates on more than one file, it handles each file according to +its current state; thus, it might lock one file, but check in another +file. This could be confusing; it is up to you to avoid confusing +behavior by marking a set of files that are in a similar state. + + If any files call for check-in, @kbd{v v} reads a single log entry, +then uses it for all the files being checked in. This is convenient for +registering or checking in several files at once, as part of the same +change. + +@findex vc-dired-toggle-terse-mode +@findex vc-dired-mark-locked + You can toggle between terse display (only locked files, or files not +up-to-date) and full display at any time by typing @kbd{v t} +@code{vc-dired-toggle-terse-mode}. There is also a special command +@kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently +locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l +t k} is another way to delete from the buffer all files except those +currently locked. + +@node Branches +@subsection Multiple Branches of a File +@cindex branch (version control) +@cindex trunk (version control) + + One use of version control is to maintain multiple ``current'' +versions of a file. For example, you might have different versions of a +program in which you are gradually adding various unfinished new +features. Each such independent line of development is called a +@dfn{branch}. VC allows you to create branches, switch between +different branches, and merge changes from one branch to another. +Please note, however, that branches are only supported for RCS at the +moment. + + A file's main line of development is usually called the @dfn{trunk}. +The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At +any such version, you can start an independent branch. A branch +starting at version 1.2 would have version number 1.2.1.1, and consecutive +versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, +and so on. If there is a second branch also starting at version 1.2, it +would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. + +@cindex head version + If you omit the final component of a version number, that is called a +@dfn{branch number}. It refers to the highest existing version on that +branch---the @dfn{head version} of that branch. The branches in the +example above have branch numbers 1.2.1 and 1.2.2. + +@menu +* Switching Branches:: How to get to another existing branch. +* Creating Branches:: How to start a new branch. +* Merging:: Transferring changes between branches. +* Multi-User Branching:: Multiple users working at multiple branches + in parallel. +@end menu + +@node Switching Branches +@subsubsection Switching between Branches + + To switch between branches, type @kbd{C-u C-x C-q} and specify the +version number you want to select. This version is then visited +@emph{unlocked} (write-protected), so you can examine it before locking +it. Switching branches in this way is allowed only when the file is not +locked. + + You can omit the minor version number, thus giving only the branch +number; this takes you to the head version on the chosen branch. If you +only type @key{RET}, Emacs goes to the highest version on the trunk. + + After you have switched to any branch (including the main branch), you +stay on it for subsequent VC commands, until you explicitly select some +other branch. + +@node Creating Branches +@subsubsection Creating New Branches + + To create a new branch from a head version (one that is the latest in +the branch that contains it), first select that version if necessary, +lock it with @kbd{C-x C-q}, and make whatever changes you want. Then, +when you check in the changes, use @kbd{C-u C-x C-q}. This lets you +specify the version number for the new version. You should specify a +suitable branch number for a branch starting at the current version. +For example, if the current version is 2.5, the branch number should be +2.5.1, 2.5.2, and so on, depending on the number of existing branches at +that point. + + To create a new branch at an older version (one that is no longer the +head of a branch), first select that version (@pxref{Switching +Branches}), then lock it with @kbd{C-x C-q}. You'll be asked to +confirm, when you lock the old version, that you really mean to create a +new branch---if you say no, you'll be offered a chance to lock the +latest version instead. + + Then make your changes and type @kbd{C-x C-q} again to check in a new +version. This automatically creates a new branch starting from the +selected version. You need not specially request a new branch, because +that's the only way to add a new version at a point that is not the head +of a branch. + + After the branch is created, you ``stay'' on it. That means that +subsequent check-ins create new versions on that branch. To leave the +branch, you must explicitly select a different version with @kbd{C-u C-x +C-q}. To transfer changes from one branch to another, use the merge +command, described in the next section. + +@node Merging +@subsubsection Merging Branches + +@cindex merging changes + When you have finished the changes on a certain branch, you will +often want to incorporate them into the file's main line of development +(the trunk). This is not a trivial operation, because development might +also have proceeded on the trunk, so that you must @dfn{merge} the +changes into a file that has already been changed otherwise. VC allows +you to do this (and other things) with the @code{vc-merge} command. + +@table @kbd +@item C-x v m (vc-merge) +Merge changes into the work file. +@end table + +@kindex C-x v m +@findex vc-merge + @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it +into the current version of the work file. It first asks you for a +branch number or a pair of version numbers in the minibuffer. Then it +finds the changes from that branch, or between the two versions you +specified, and merges them into the current version of the current file. + + As an example, suppose that you have finished a certain feature on +branch 1.3.1. In the meantime, development on the trunk has proceeded +to version 1.5. To merge the changes from the branch to the trunk, +first go to the head version of the trunk, by typing @kbd{C-u C-x C-q +RET}. Version 1.5 is now current. If locking is used for the file, +type @kbd{C-x C-q} to lock version 1.5 so that you can change it. Next, +type @kbd{C-x v m 1.3.1 RET}. This takes the entire set of changes on +branch 1.3.1 (relative to version 1.3, where the branch started, up to +the last version on the branch) and merges it into the current version +of the work file. You can now check in the changed file, thus creating +version 1.6 containing the changes from the branch. + + It is possible to do further editing after merging the branch, before +the next check-in. But it is usually wiser to check in the merged +version, then lock it and make the further changes. This will keep +a better record of the history of changes. + +@cindex conflicts +@cindex resolving conflicts + When you merge changes into a file that has itself been modified, the +changes might overlap. We call this situation a @dfn{conflict}, and +reconciling the conflicting changes is called @dfn{resolving a +conflict}. + + Whenever conflicts occur during merging, VC detects them, tells you +about them in the echo area, and asks whether you want help in merging. +If you say yes, it starts an Ediff session (@pxref{Top, +Ediff, Ediff, ediff, The Ediff Manual}). + + If you say no, the conflicting changes are both inserted into the +file, surrounded by @dfn{conflict markers}. The example below shows how +a conflict region looks; the file is called @samp{name} and the current +master file version with user B's changes in it is 1.11. + +@c @w here is so CVS won't think this is a conflict. +@smallexample +@group +@w{<}<<<<<< name + @var{User A's version} +======= + @var{User B's version} +@w{>}>>>>>> 1.11 +@end group +@end smallexample + +@cindex vc-resolve-conflicts + Then you can resolve the conflicts by editing the file manually. Or +you can type @code{M-x vc-resolve-conflicts} after visiting the file. +This starts an Ediff session, as described above. + +@node Multi-User Branching +@subsubsection Multi-User Branching + + It is often useful for multiple developers to work simultaneously on +different branches of a file. CVS allows this by default; for RCS, it +is possible if you create multiple source directories. Each source +directory should have a link named @file{RCS} which points to a common +directory of RCS master files. Then each source directory can have its +own choice of selected versions, but all share the same common RCS +records. + + This technique works reliably and automatically, provided that the +source files contain RCS version headers (@pxref{Version Headers}). The +headers enable Emacs to be sure, at all times, which version number is +present in the work file. + + If the files do not have version headers, you must instead tell Emacs +explicitly in each session which branch you are working on. To do this, +first find the file, then type @kbd{C-u C-x C-q} and specify the correct +branch number. This ensures that Emacs knows which branch it is using +during this particular editing session. + +@node Snapshots +@subsection Snapshots +@cindex snapshots and version control + + A @dfn{snapshot} is a named set of file versions (one for each +registered file) that you can treat as a unit. One important kind of +snapshot is a @dfn{release}, a (theoretically) stable version of the +system that is ready for distribution to users. + +@menu +* Making Snapshots:: The snapshot facilities. +* Snapshot Caveats:: Things to be careful of when using snapshots. +@end menu + +@node Making Snapshots +@subsubsection Making and Using Snapshots + + There are two basic commands for snapshots; one makes a +snapshot with a given name, the other retrieves a named snapshot. + +@table @code +@kindex C-x v s +@findex vc-create-snapshot +@item C-x v s @var{name} @key{RET} +Define the last saved versions of every registered file in or under the +current directory as a snapshot named @var{name} +(@code{vc-create-snapshot}). + +@kindex C-x v r +@findex vc-retrieve-snapshot +@item C-x v r @var{name} @key{RET} +For all registered files at or below the current directory level, select +whatever versions correspond to the snapshot @var{name} +(@code{vc-retrieve-snapshot}). + +This command reports an error if any files are locked at or below the +current directory, without changing anything; this is to avoid +overwriting work in progress. +@end table + + A snapshot uses a very small amount of resources---just enough to record +the list of file names and which version belongs to the snapshot. Thus, +you need not hesitate to create snapshots whenever they are useful. + + You can give a snapshot name as an argument to @kbd{C-x v =} or +@kbd{C-x v ~} (@pxref{Old Versions}). Thus, you can use it to compare a +snapshot against the current files, or two snapshots against each other, +or a snapshot against a named version. + +@node Snapshot Caveats +@subsubsection Snapshot Caveats + +@cindex named configurations (RCS) + VC's snapshot facilities are modeled on RCS's named-configuration +support. They use RCS's native facilities for this, so under VC +snapshots made using RCS are visible even when you bypass VC. + +@c worded verbosely to avoid overfull hbox. + For SCCS, VC implements snapshots itself. The files it uses contain +name/file/version-number triples. These snapshots are visible only +through VC. + + A snapshot is a set of checked-in versions. So make sure that all the +files are checked in and not locked when you make a snapshot. + + File renaming and deletion can create some difficulties with snapshots. +This is not a VC-specific problem, but a general design issue in version +control systems that no one has solved very well yet. + + If you rename a registered file, you need to rename its master along +with it (the command @code{vc-rename-file} does this automatically). If +you are using SCCS, you must also update the records of the snapshot, to +mention the file by its new name (@code{vc-rename-file} does this, +too). An old snapshot that refers to a master file that no longer +exists under the recorded name is invalid; VC can no longer retrieve +it. It would be beyond the scope of this manual to explain enough about +RCS and SCCS to explain how to update the snapshots by hand. + + Using @code{vc-rename-file} makes the snapshot remain valid for +retrieval, but it does not solve all problems. For example, some of the +files in the program probably refer to others by name. At the very +least, the makefile probably mentions the file that you renamed. If you +retrieve an old snapshot, the renamed file is retrieved under its new +name, which is not the name that the makefile expects. So the program +won't really work as retrieved. + +@node Miscellaneous VC +@subsection Miscellaneous Commands and Features of VC + + This section explains the less-frequently-used features of VC. + +@menu +* Change Logs and VC:: Generating a change log file from log entries. +* Renaming and VC:: A command to rename both the source and master + file correctly. +* Version Headers:: Inserting version control headers into working files. +@end menu + +@node Change Logs and VC +@subsubsection Change Logs and VC + + If you use RCS or CVS for a program and also maintain a change log +file for it (@pxref{Change Log}), you can generate change log entries +automatically from the version control log entries: + +@table @kbd +@item C-x v a +@kindex C-x v a +@findex vc-update-change-log +Visit the current directory's change log file and, for registered files +in that directory, create new entries for versions checked in since the +most recent entry in the change log file. +(@code{vc-update-change-log}). + +This command works with RCS or CVS only, not with SCCS. + +@item C-u C-x v a +As above, but only find entries for the current buffer's file. + +@item M-1 C-x v a +As above, but find entries for all the currently visited files that are +maintained with version control. This works only with RCS, and it puts +all entries in the log for the default directory, which may not be +appropriate. +@end table + + For example, suppose the first line of @file{ChangeLog} is dated +1999-04-10, and that the only check-in since then was by Nathaniel +Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log +messages that start with `#'.}. Then @kbd{C-x v a} visits +@file{ChangeLog} and inserts text like this: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-05-22 Nathaniel Bowditch <nat@@apn.org> + + * rcs2log: Ignore log messages that start with `#'. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + +@noindent +You can then edit the new change log entry further as you wish. + + Unfortunately, timestamps in ChangeLog files are only dates, so some +of the new change log entry may duplicate what's already in ChangeLog. +You will have to remove these duplicates by hand. + + Normally, the log entry for file @file{foo} is displayed as @samp{* +foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted +if the text of the log entry starts with @w{@samp{(@var{functionname}): +}}. For example, if the log entry for @file{vc.el} is +@samp{(vc-do-command): Check call-process status.}, then the text in +@file{ChangeLog} looks like this: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-05-06 Nathaniel Bowditch <nat@@apn.org> + + * vc.el (vc-do-command): Check call-process status. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + + When @kbd{C-x v a} adds several change log entries at once, it groups +related log entries together if they all are checked in by the same +author at nearly the same time. If the log entries for several such +files all have the same text, it coalesces them into a single entry. +For example, suppose the most recent check-ins have the following log +entries: + +@flushleft +@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} +@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} +@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} +@end flushleft + +@noindent +They appear like this in @file{ChangeLog}: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-04-01 Nathaniel Bowditch <nat@@apn.org> + + * vc.texinfo: Fix expansion typos. + + * vc.el, vc-hooks.el: Don't call expand-file-name. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + + Normally, @kbd{C-x v a} separates log entries by a blank line, but you +can mark several related log entries to be clumped together (without an +intervening blank line) by starting the text of each related log entry +with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label +itself is not copied to @file{ChangeLog}. For example, suppose the log +entries are: + +@flushleft +@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} +@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} +@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} +@end flushleft + +@noindent +Then the text in @file{ChangeLog} looks like this: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-04-01 Nathaniel Bowditch <nat@@apn.org> + + * vc.texinfo: Fix expansion typos. + * vc.el, vc-hooks.el: Don't call expand-file-name. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + + A log entry whose text begins with @samp{#} is not copied to +@file{ChangeLog}. For example, if you merely fix some misspellings in +comments, you can log the change with an entry beginning with @samp{#} +to avoid putting such trivia into @file{ChangeLog}. + +@node Renaming and VC +@subsubsection Renaming VC Work Files and Master Files + +@findex vc-rename-file + When you rename a registered file, you must also rename its master +file correspondingly to get proper results. Use @code{vc-rename-file} +to rename the source file as you specify, and rename its master file +accordingly. It also updates any snapshots (@pxref{Snapshots}) that +mention the file, so that they use the new name; despite this, the +snapshot thus modified may not completely work (@pxref{Snapshot +Caveats}). + + You cannot use @code{vc-rename-file} on a file that is locked by +someone else. + +@node Version Headers +@subsubsection Inserting Version Control Headers + + Sometimes it is convenient to put version identification strings +directly into working files. Certain special strings called +@dfn{version headers} are replaced in each successive version by the +number of that version. + + If you are using RCS, and version headers are present in your working +files, Emacs can use them to determine the current version and the +locking state of the files. This is more reliable than referring to the +master files, which is done when there are no version headers. Note +that in a multi-branch environment, version headers are necessary to +make VC behave correctly (@pxref{Multi-User Branching}). + + Searching for version headers is controlled by the variable +@code{vc-consult-headers}. If it is non-@code{nil}, Emacs searches for +headers to determine the version number you are editing. Setting it to +@code{nil} disables this feature. + +@kindex C-x v h +@findex vc-insert-headers + You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to +insert a suitable header string. + +@table @kbd +@item C-x v h +Insert headers in a file for use with your version-control system. +@end table + +@vindex vc-header-alist + The default header string is @samp{@w{$}Id$} for RCS and +@samp{@w{%}W%} for SCCS. You can specify other headers to insert by +setting the variable @code{vc-header-alist}. Its value is a list of +elements of the form @code{(@var{program} . @var{string})} where +@var{program} is @code{RCS} or @code{SCCS} and @var{string} is the +string to use. + + Instead of a single string, you can specify a list of strings; then +each string in the list is inserted as a separate header on a line of +its own. + + It is often necessary to use ``superfluous'' backslashes when writing +the strings that you put in this variable. This is to prevent the +string in the constant from being interpreted as a header itself if the +Emacs Lisp file containing it is maintained with version control. + +@vindex vc-comment-alist + Each header is inserted surrounded by tabs, inside comment delimiters, +on a new line at point. Normally the ordinary comment +start and comment end strings of the current mode are used, but for +certain modes, there are special comment delimiters for this purpose; +the variable @code{vc-comment-alist} specifies them. Each element of +this list has the form @code{(@var{mode} @var{starter} @var{ender})}. + +@vindex vc-static-header-alist + The variable @code{vc-static-header-alist} specifies further strings +to add based on the name of the buffer. Its value should be a list of +elements of the form @code{(@var{regexp} . @var{format})}. Whenever +@var{regexp} matches the buffer name, @var{format} is inserted as part +of the header. A header line is inserted for each element that matches +the buffer name, and for each string specified by +@code{vc-header-alist}. The header line is made by processing the +string from @code{vc-header-alist} with the format taken from the +element. The default value for @code{vc-static-header-alist} is as follows: + +@example +@group +(("\\.c$" . + "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ +#endif /* lint */\n")) +@end group +@end example + +@noindent +It specifies insertion of text of this form: + +@example +@group + +#ifndef lint +static char vcid[] = "@var{string}"; +#endif /* lint */ +@end group +@end example + +@noindent +Note that the text above starts with a blank line. + + If you use more than one version header in a file, put them close +together in the file. The mechanism in @code{revert-buffer} that +preserves markers may not handle markers positioned between two version +headers. + +@node Customizing VC +@subsection Customizing VC + + There are many ways of customizing VC. The options you can set fall +into four categories, described in the following sections. + +@menu +* Backend Options:: Customizing the back-end to your needs. +* VC Workfile Handling:: Various options concerning working files. +* VC Status Retrieval:: How VC finds the version control status of a file, + and how to customize this. +* VC Command Execution:: Which commands VC should run, and how. +@end menu + +@node Backend Options +@subsubsection Options for VC Backends + +@cindex backend options (VC) +@cindex locking under version control + You can tell RCS and CVS whether to use locking for a file or not +(@pxref{VC Concepts}, for a description of locking). VC automatically +recognizes what you have chosen, and behaves accordingly. + +@cindex non-strict locking (RCS) +@cindex locking, non-strict (RCS) + For RCS, the default is to use locking, but there is a mode called +@dfn{non-strict locking} in which you can check-in changes without +locking the file first. Use @samp{rcs -U} to switch to non-strict +locking for a particular file, see the @samp{rcs} manpage for details. + +@cindex locking (CVS) + Under CVS, the default is not to use locking; anyone can change a work +file at any time. However, there are ways to restrict this, resulting +in behavior that resembles locking. + +@cindex CVSREAD environment variable (CVS) + For one thing, you can set the @code{CVSREAD} environment variable to +an arbitrary value. If this variable is defined, CVS makes your work +files read-only by default. In Emacs, you must type @kbd{C-x C-q} to +make the file writeable, so that editing works in fact similar as if +locking was used. Note however, that no actual locking is performed, so +several users can make their files writeable at the same time. When +setting @code{CVSREAD} for the first time, make sure to check out all +your modules anew, so that the file protections are set correctly. + +@cindex cvs watch feature +@cindex watching files (CVS) + Another way to achieve something similar to locking is to use the +@dfn{watch} feature of CVS. If a file is being watched, CVS makes it +read-only by default, and you must also use @kbd{C-x C-q} in Emacs to +make it writable. VC calls @code{cvs edit} to make the file writeable, +and CVS takes care to notify other developers of the fact that you +intend to change the file. See the CVS documentation for details on +using the watch feature. + +@vindex vc-handle-cvs + You can turn off use of VC for CVS-managed files by setting the +variable @code{vc-handle-cvs} to @code{nil}. If you do this, Emacs +treats these files as if they were not registered, and the VC commands +are not available for them. You must do all CVS operations manually. + +@node VC Workfile Handling +@subsubsection VC Workfile Handling + +@vindex vc-make-backup-files + Emacs normally does not save backup files for source files that are +maintained with version control. If you want to make backup files even +for files that use version control, set the variable +@code{vc-make-backup-files} to a non-@code{nil} value. + +@vindex vc-keep-workfiles + Normally the work file exists all the time, whether it is locked or +not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking +in a new version with @kbd{C-x C-q} deletes the work file; but any +attempt to visit the file with Emacs creates it again. (With CVS, work +files are always kept.) + +@vindex vc-follow-symlinks + Editing a version-controlled file through a symbolic link can be +dangerous. It bypasses the version control system---you can edit the +file without locking it, and fail to check your changes in. Also, +your changes might overwrite those of another user. To protect against +this, VC checks each symbolic link that you visit, to see if it points +to a file under version control. + + The variable @code{vc-follow-symlinks} controls what to do when a +symbolic link points to a version-controlled file. If it is @code{nil}, +VC only displays a warning message. If it is @code{t}, VC automatically +follows the link, and visits the real file instead, telling you about +this in the echo area. If the value is @code{ask} (the default), VC +asks you each time whether to follow the link. + +@node VC Status Retrieval +@subsubsection VC Status Retrieval +@c There is no need to tell users about vc-master-templates. + + When deducing the locked/unlocked state of a file, VC first looks for +an RCS version header string in the file (@pxref{Version Headers}). If +there is no header string, or if you are using SCCS, VC normally looks +at the file permissions of the work file; this is fast. But there might +be situations when the file permissions cannot be trusted. In this case +the master file has to be consulted, which is rather expensive. Also +the master file can only tell you @emph{if} there's any lock on the +file, but not whether your work file really contains that locked +version. + +@vindex vc-consult-headers + You can tell VC not to use version headers to determine lock status by +setting @code{vc-consult-headers} to @code{nil}. VC then always uses +the file permissions (if it can trust them), or else checks the master +file. + +@vindex vc-mistrust-permissions + You can specify the criterion for whether to trust the file +permissions by setting the variable @code{vc-mistrust-permissions}. Its +value can be @code{t} (always mistrust the file permissions and check +the master file), @code{nil} (always trust the file permissions), or a +function of one argument which makes the decision. The argument is the +directory name of the @file{RCS}, @file{CVS} or @file{SCCS} +subdirectory. A non-@code{nil} value from the function says to mistrust +the file permissions. If you find that the file permissions of work +files are changed erroneously, set @code{vc-mistrust-permissions} to +@code{t}. Then VC always checks the master file to determine the file's +status. + +@node VC Command Execution +@subsubsection VC Command Execution + +@vindex vc-suppress-confirm + If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q} +and @kbd{C-x v i} can save the current buffer without asking, and +@kbd{C-x v u} also operates without asking for confirmation. (This +variable does not affect @kbd{C-x v c}; that operation is so drastic +that it should always ask for confirmation.) + +@vindex vc-command-messages + VC mode does much of its work by running the shell commands for RCS, +CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC +displays messages to indicate which shell commands it runs, and +additional messages when the commands finish. + +@vindex vc-path + You can specify additional directories to search for version control +programs by setting the variable @code{vc-path}. These directories are +searched before the usual search path. But the proper files are usually +found automatically. + +@node Directories +@section File Directories + +@cindex file directory +@cindex directory listing + The file system groups files into @dfn{directories}. A @dfn{directory +listing} is a list of all the files in a directory. Emacs provides +commands to create and delete directories, and to make directory +listings in brief format (file names only) and verbose format (sizes, +dates, and authors included). There is also a directory browser called +Dired; see @ref{Dired}. + +@table @kbd +@item C-x C-d @var{dir-or-pattern} @key{RET} +Display a brief directory listing (@code{list-directory}). +@item C-u C-x C-d @var{dir-or-pattern} @key{RET} +Display a verbose directory listing. +@item M-x make-directory @key{RET} @var{dirname} @key{RET} +Create a new directory named @var{dirname}. +@item M-x delete-directory @key{RET} @var{dirname} @key{RET} +Delete the directory named @var{dirname}. It must be empty, +or you get an error. +@end table + +@findex list-directory +@kindex C-x C-d + The command to display a directory listing is @kbd{C-x C-d} +(@code{list-directory}). It reads using the minibuffer a file name +which is either a directory to be listed or a wildcard-containing +pattern for the files to be listed. For example, + +@example +C-x C-d /u2/emacs/etc @key{RET} +@end example + +@noindent +lists all the files in directory @file{/u2/emacs/etc}. Here is an +example of specifying a file name pattern: + +@example +C-x C-d /u2/emacs/src/*.c @key{RET} +@end example + + Normally, @kbd{C-x C-d} prints a brief directory listing containing +just file names. A numeric argument (regardless of value) tells it to +make a verbose listing including sizes, dates, and authors (like +@samp{ls -l}). + +@vindex list-directory-brief-switches +@vindex list-directory-verbose-switches + The text of a directory listing is obtained by running @code{ls} in an +inferior process. Two Emacs variables control the switches passed to +@code{ls}: @code{list-directory-brief-switches} is a string giving the +switches to use in brief listings (@code{"-CF"} by default), and +@code{list-directory-verbose-switches} is a string giving the switches to +use in a verbose listing (@code{"-l"} by default). + +@node Comparing Files +@section Comparing Files +@cindex comparing files + +@findex diff +@vindex diff-switches + The command @kbd{M-x diff} compares two files, displaying the +differences in an Emacs buffer named @samp{*Diff*}. It works by running +the @code{diff} program, using options taken from the variable +@code{diff-switches}, whose value should be a string. + + The buffer @samp{*Diff*} has Compilation mode as its major mode, so +you can use @kbd{C-x `} to visit successive changed locations in the two +source files. You can also move to a particular hunk of changes and +type @key{RET} or @kbd{C-c C-c}, or click @kbd{Mouse-2} on it, to move +to the corresponding source location. You can also use the other +special commands of Compilation mode: @key{SPC} and @key{DEL} for +scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion. +@xref{Compilation}. + +@findex diff-backup + The command @kbd{M-x diff-backup} compares a specified file with its most +recent backup. If you specify the name of a backup file, +@code{diff-backup} compares it with the source file that it is a backup +of. + +@findex compare-windows + The command @kbd{M-x compare-windows} compares the text in the current +window with that in the next window. Comparison starts at point in each +window, and each starting position is pushed on the mark ring in its +respective buffer. Then point moves forward in each window, a character +at a time, until a mismatch between the two windows is reached. Then +the command is finished. For more information about windows in Emacs, +@ref{Windows}. + +@vindex compare-ignore-case + With a numeric argument, @code{compare-windows} ignores changes in +whitespace. If the variable @code{compare-ignore-case} is +non-@code{nil}, it ignores differences in case as well. + + See also @ref{Emerge}, for convenient facilities for merging two +similar files. + +@node Misc File Ops +@section Miscellaneous File Operations + + Emacs has commands for performing many other operations on files. +All operate on one file; they do not accept wildcard file names. + +@findex view-file +@cindex viewing +@cindex View mode +@cindex mode, View + @kbd{M-x view-file} allows you to scan or read a file by sequential +screenfuls. It reads a file name argument using the minibuffer. After +reading the file into an Emacs buffer, @code{view-file} displays the +beginning. You can then type @key{SPC} to scroll forward one windowful, +or @key{DEL} to scroll backward. Various other commands are provided +for moving around in the file, but none for changing it; type @kbd{?} +while viewing for a list of them. They are mostly the same as normal +Emacs cursor motion commands. To exit from viewing, type @kbd{q}. +The commands for viewing are defined by a special major mode called View +mode. + + A related command, @kbd{M-x view-buffer}, views a buffer already present +in Emacs. @xref{Misc Buffer}. + +@findex insert-file + @kbd{M-x insert-file} inserts a copy of the contents of the specified +file into the current buffer at point, leaving point unchanged before the +contents and the mark after them. + +@findex write-region + @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it +copies the contents of the region into the specified file. @kbd{M-x +append-to-file} adds the text of the region to the end of the specified +file. @xref{Accumulating Text}. + +@findex delete-file +@cindex deletion (of files) + @kbd{M-x delete-file} deletes the specified file, like the @code{rm} +command in the shell. If you are deleting many files in one directory, it +may be more convenient to use Dired (@pxref{Dired}). + +@findex rename-file + @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using +the minibuffer, then renames file @var{old} as @var{new}. If a file named +@var{new} already exists, you must confirm with @kbd{yes} or renaming is not +done; this is because renaming causes the old meaning of the name @var{new} +to be lost. If @var{old} and @var{new} are on different file systems, the +file @var{old} is copied and deleted. + +@findex add-name-to-file + The similar command @kbd{M-x add-name-to-file} is used to add an +additional name to an existing file without removing its old name. +The new name must belong on the same file system that the file is on. + +@findex copy-file +@cindex copying files + @kbd{M-x copy-file} reads the file @var{old} and writes a new file named +@var{new} with the same contents. Confirmation is required if a file named +@var{new} already exists, because copying has the consequence of overwriting +the old contents of the file @var{new}. + +@findex make-symbolic-link + @kbd{M-x make-symbolic-link} reads two file names @var{target} and +@var{linkname}, then creates a symbolic link named @var{linkname} and +pointing at @var{target}. The effect is that future attempts to open file +@var{linkname} will refer to whatever file is named @var{target} at the +time the opening is done, or will get an error if the name @var{target} is +not in use at that time. This command does not expand the argument +@var{target}, so that it allows you to specify a relative name +as the target of the link. + + Confirmation is required when creating the link if @var{linkname} is +in use. Note that not all systems support symbolic links. + +@node Compressed Files +@section Accessing Compressed Files +@cindex compression +@cindex uncompression +@cindex Auto Compression mode +@cindex mode, Auto Compression +@pindex gzip + +@findex auto-compression-mode + Emacs comes with a library that can automatically uncompress +compressed files when you visit them, and automatically recompress them +if you alter them and save them. To enable this feature, type the +command @kbd{M-x auto-compression-mode}. + + When automatic compression (which implies automatic uncompression as +well) is enabled, Emacs recognizes compressed files by their file names. +File names ending in @samp{.gz} indicate a file compressed with +@code{gzip}. Other endings indicate other compression programs. + + Automatic uncompression and compression apply to all the operations in +which Emacs uses the contents of a file. This includes visiting it, +saving it, inserting its contents into a buffer, loading it, and byte +compiling it. + +@node Remote Files +@section Remote Files + +@cindex FTP +@cindex remote file access + You can refer to files on other machines using a special file name syntax: + +@example +@group +/@var{host}:@var{filename} +/@var{user}@@@var{host}:@var{filename} +@end group +@end example + +@noindent +When you do this, Emacs uses the FTP program to read and write files on +the specified host. It logs in through FTP using your user name or the +name @var{user}. It may ask you for a password from time to time; this +is used for logging in on @var{host}. + +@cindex ange-ftp +@vindex ange-ftp-default-user + Normally, if you do not specify a user name in a remote file name, +that means to use your own user name. But if you set the variable +@code{ange-ftp-default-user} to a string, that string is used instead. +(The Emacs package that implements FTP file access is called +@code{ange-ftp}.) + +@vindex file-name-handler-alist + You can entirely turn off the FTP file name feature by setting the +variable @code{file-name-handler-alist} to @code{nil}. + +@node Quoted File Names +@section Quoted File Names + +@cindex quoting file names + You can @dfn{quote} an absolute file name to prevent special +characters and syntax in it from having their special effects. +The way to do this is to add @samp{/:} at the beginning. + + For example, you can quote a local file name which appears remote, to +prevent it from being treated as a remote file name. Thus, if you have +a directory named @file{/foo:} and a file named @file{bar} in it, you +can refer to that file in Emacs as @samp{/:/foo:/bar}. + + @samp{/:} can also prevent @samp{~} from being treated as a special +character for a user's home directory. For example, @file{/:/tmp/~hack} +refers to a file whose name is @file{~hack} in directory @file{/tmp}. + + Likewise, quoting with @samp{/:} is one way to enter in the minibuffer +a file name that contains @samp{$}. However, the @samp{/:} must be at +the beginning of the buffer in order to quote @samp{$}. + + You can also quote wildcard characters with @samp{/:}, for visiting. +For example, @file{/:/tmp/foo*bar} visits the file @file{/tmp/foo*bar}. +However, in most cases you can simply type the wildcard characters for +themselves. For example, if the only file name in @file{/tmp} that +starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, then +specifying @file{/tmp/foo*bar} will visit just @file{/tmp/foo*bar}. + |