Mercurial > emacs
changeset 84153:21a64edde163
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:36:21 +0000 |
| parents | 5e43166d9d06 |
| children | b1b8da4e0ccd |
| files | man/files.texi |
| diffstat | 1 files changed, 0 insertions(+), 2950 deletions(-) [+] |
line wrap: on
line diff
--- a/man/files.texi Thu Sep 06 04:36:15 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2950 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Files, Buffers, Keyboard Macros, 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. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex -* 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. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other sites. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. -@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 -(@pxref{Completion}) to make it easier to specify long file names. When -completing file names, Emacs ignores those whose file-name extensions -appear in the variable @code{completion-ignored-extensions}; see -@ref{Completion Options}. - - 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 which is 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. - -@findex cd -@findex pwd - The command @kbd{M-x pwd} displays 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 it visits. 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. - - For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} -then the default directory is normally @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}. - -@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}. - -@cindex home directory shorthand - You can use @file{~/} in a file name to mean your home directory, -or @file{~@var{user-id}/} to mean the home directory of a user whose -login name is @code{user-id}@footnote{ -On MS-Windows and MS-DOS systems, where a user doesn't have a home -directory, Emacs replaces @file{~/} with the value of the -environment variable @code{HOME}; see @ref{General Variables}. On -these systems, the @file{~@var{user-id}/} construct is supported only -for the current user, i.e., only if @var{user-id} is the current -user's login name.}. - -@cindex environment variables in file names -@cindex expansion of environment variables -@cindex @code{$} in file names - @anchor{File Names with $}@samp{$} in a file name is used to -substitute an environment variable. The environment variable name -consists of all the alphanumeric characters after the @samp{$}; -alternatively, it can be enclosed in braces after the @samp{$}. For -example, if you have used the shell command @command{export -FOO=rms/hacks} to set up an environment variable named @env{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}. If the environment -variable is not defined, no substitution occurs: @file{/u/$notdefined} -stands for itself (assuming the environment variable @env{notdefined} -is not defined). - - Note that shell commands to set environment variables affect Emacs -only when done before Emacs is started. - - To access a file with @samp{$} in its name, if the @samp{$} causes -expansion, type @samp{$$}. This pair is converted to a single -@samp{$} at the same time as variable substitution is performed for a -single @samp{$}. Alternatively, quote the whole file name with -@samp{/:} (@pxref{Quoted File Names}). File names which begin with a -literal @samp{~} should also be quoted with @samp{/:}. - -@findex substitute-in-file-name - The Lisp function that performs the @samp{$}-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-@acronym{ASCII} characters in file names if you set the -variable @code{file-name-coding-system} to a non-@code{nil} value. -@xref{File Name Coding}. - -@node Visiting -@section Visiting Files -@cindex visiting files -@cindex open file - -@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 saving files - @dfn{Visiting} a file means reading its contents into an Emacs -buffer so you can edit them. Emacs makes a new buffer for each file -that you visit. We often say that this buffer ``is visiting'' that -file, or that the buffer's ``visited file'' is that file. 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, Emacs constructs a unique -name---the normal method is to append @samp{<2>}, @samp{<3>}, and so -on, but you can select other methods (@pxref{Uniquify}). - - 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 -permanent place, 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}. File-name completion ignores certain file names; for more -about this, see @ref{Completion Options}. - - 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 you could not -create it, or exists but you can't read it, 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 whether the file itself has changed -since you visited or saved it last. If the file has changed, Emacs offers -to reread it. - -@vindex large-file-warning-threshold -@cindex maximum buffer size exceeded, error message - If you try to visit a file larger than -@code{large-file-warning-threshold} (the default is 10000000, which is -about 10 megabytes), Emacs will ask you for confirmation first. You -can answer @kbd{y} to proceed with visiting the file. Note, however, -that Emacs cannot visit files that are larger than the maximum Emacs -buffer size, which is around 256 megabytes on 32-bit machines -(@pxref{Buffers}). If you try, Emacs will display an error message -saying that the maximum buffer size has been exceeded. - -@cindex file selection dialog - On graphical displays there are two additional methods for -visiting files. Firstly, when Emacs is built with a suitable GUI -toolkit, commands invoked with the mouse (by clicking on the menu bar -or tool bar) use the toolkit's standard File Selection dialog instead -of prompting for the file name in the minibuffer. On Unix and -GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and -Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. -For information on how to customize this, see @ref{Dialog Boxes}. - - Secondly, Emacs supports ``drag and drop''; dropping a file into an -ordinary Emacs window visits the file using that window. However, -dropping a file into a window displaying a Dired buffer moves or -copies the file into the displayed directory. For details, see -@ref{Drag and Drop}, and @ref{Misc Dired Features}. - -@cindex creating files - What if you want to create a new file? Just visit it. Emacs displays -@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 end-of-line -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 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 view, delete, -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. - - Files which are actually collections of other files, or @dfn{file -archives}, are visited in special modes which invoke a Dired-like -environment to allow operations on archive members. @xref{File -Archives}, for more about these features. - -@cindex wildcard characters in file names -@vindex find-file-wildcards - If the file name you specify contains shell-style wildcard -characters, Emacs visits all the files that match it. (On -case-insensitive filesystems, Emacs matches the wildcards disregarding -the letter case.) Wildcards include @samp{?}, @samp{*}, and -@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file -name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted -File Names}, for information on how to visit a file whose name -actually contains wildcard characters. You can disable the wildcard -feature by customizing @code{find-file-wildcards}. - - If you visit a file that the operating system won't let you modify, -or that is marked read-only, Emacs makes the buffer read-only too, 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{toggle-read-only}). @xref{Misc Buffer}. - -@kindex C-x C-r -@findex find-file-read-only - If you want to visit a file as read-only in order to protect -yourself from entering changes accidentally, visit it with the command -@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. - -@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 -@kbd{C-x C-v} 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. - -@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 @acronym{ASCII} 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}), and -does not add a final newline because of @code{require-final-newline}. -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-hook -@vindex find-file-not-found-functions - 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-functions}; 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{-functions} rather than @samp{-hook} -to indicate that fact. - - Successful visiting of any file, whether existing or not, calls the -functions in the list @code{find-file-hook}, with no arguments. -This variable is a normal hook. In the case of a nonexistent file, the -@code{find-file-not-found-functions} 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. - -@menu -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* Shadowing: File Shadowing. Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. -@end menu - -@node Save Commands -@subsection Commands for Saving Files - - These are the commands that relate to saving and writing files. - -@table @kbd -@item C-x C-s -Save the current buffer in its visited file on disk (@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}). -With prefix argument (@kbd{C-u}), mark the current buffer as changed. -@item C-x C-w -Save the current buffer with a specified file name (@code{write-file}). -@item M-x set-visited-file-name -Change the file 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 d -Diff the buffer against its corresponding file, so you can see -what changes you would be saving. -@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.) You can also kill the buffer. - -@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 marks the buffer as visiting that file name, and -changes the buffer name correspondingly. @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 -equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s} -(except that @kbd{C-x C-w} asks for confirmation if the file exists). -@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 (@pxref{File Names}). - - 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}. - -@node Backup -@subsection Backup Files -@cindex backup file -@vindex make-backup-files -@vindex vc-make-backup-files - - 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. -@iftex -@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{General VC Options}. -@end ifnottex - - - At your option, Emacs can keep either a single backup for each file, -or make a series of numbered backup files for each file that you edit. - -@vindex backup-enable-predicate -@vindex temporary-file-directory -@vindex small-temporary-file-directory - The default value of the @code{backup-enable-predicate} variable -prevents backup files being written for files in the directories used -for temporary files, specified by @code{temporary-file-directory} or -@code{small-temporary-file-directory}. - - 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 -* One or Many: Numbered Backups. Whether to make one backup file or many. -* Names: Backup Names. How backup files are named. -* Deletion: Backup Deletion. Emacs deletes excess numbered backups. -* Copying: Backup Copying. Backups can be made by copying or renaming. -@end menu - -@node Numbered Backups -@subsubsection Numbered Backups - -@vindex version-control - The choice of single backup file or multiple numbered backup files -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 -Never make numbered backups; always make single backups. -@end table - -@noindent -The usual way to set this variable is globally, through your -@file{.emacs} file or the customization buffer. However, 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 @env{VERSION_CONTROL} environment variable - If you set the environment variable @env{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 Names -@subsubsection Single or Numbered Backups - - When Emacs makes a single backup file, its name is normally -constructed by appending @samp{~} to the file name being edited; thus, -the backup file for @file{eval.c} would be @file{eval.c~}. - -@vindex make-backup-file-name-function -@vindex backup-directory-alist - You can change this behavior by defining the variable -@code{make-backup-file-name-function} to a suitable function. -Alternatively you can customize the variable -@code{backup-directory-alist} to specify that files matching certain -patterns should be backed up in specific directories. - - A typical use is to add an element @code{("." . @var{dir})} to make -all backups in the directory with absolute name @var{dir}; Emacs -modifies the backup file names to avoid clashes between files with the -same names originating in different directories. Alternatively, -adding, say, @code{("." . ".~")} would make backups in the invisible -subdirectory @file{.~} of the original file's directory. Emacs -creates the directory, if necessary, to make the backup. - - If access control stops Emacs from writing backup files under the usual -names, it writes the backup file as @file{%backup%~} in your home -directory. Only one such file can exist, so only the most recently -made such backup is available. - - If you choose to have a series of numbered backup files, backup file -names contain @samp{.~}, the number, and another @samp{~} after 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, all the way -through names like @file{eval.c.~259~} and beyond. The variable -@code{backup-directory-alist} applies to numbered backups just as -usual. - -@node Backup Deletion -@subsubsection Automatic Deletion of Backups - - To prevent excessive 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. The backups in the middle (excluding those oldest -and newest) are the excess middle versions---those backups are -deleted. These variables' values are used when it is time to delete -excess versions, just after a new backup version is made; the 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 @code{t}, Emacs deletes the excess -backup files silently. If it is @code{nil}, the default, Emacs asks -you whether it should delete the excess backup versions. If it has -any other value, then Emacs never automatically deletes backups. - - 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 (hard -links). 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 -@vindex backup-by-copying-when-privileged-mismatch -@cindex file ownership, and backup -@cindex backup, and user-id - The choice of renaming or copying is controlled by four 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. The fourth variable, -@code{backup-by-copying-when-privileged-mismatch}, gives the highest -numeric user-id for which @code{backup-by-copying-when-mismatch} will be -forced on. This is useful when low-numbered user-ids are assigned to -special system users, such as @code{root}, @code{bin}, @code{daemon}, -etc., which must maintain ownership of files. - - 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 Customize Save -@subsection Customizing Saving of Files - -@vindex require-final-newline - If the value of the variable @code{require-final-newline} is -@code{t}, saving or writing a file silently puts a newline at the end -if there isn't already one there. If the value is @code{visit}, Emacs -adds a newline at the end of any file that doesn't have one, just -after it visits the file. (This marks the buffer as modified, and you -can undo it.) If the value is @code{visit-save}, that means to add -newlines both on visiting and on saving. If the value is @code{nil}, -Emacs leaves the end of the file unchanged; if it's neither @code{nil} -nor @code{t}, Emacs asks you whether to add a newline. The default is -@code{nil}. - -@vindex mode-require-final-newline - Many major modes are designed for specific kinds of files that are -always supposed to end in newlines. These major modes set the -variable @code{require-final-newline} according to -@code{mode-require-final-newline}. By setting the latter variable, -you can control how these modes handle final newlines. - -@vindex write-region-inhibit-fsync - When Emacs saves a file, it invokes the @code{fsync} system call to -force the data immediately out to disk. This is important for safety -if the system crashes or in case of power outage. However, it can be -disruptive on laptops using power saving, because it requires the disk -to spin up each time you save a file. Setting -@code{write-region-inhibit-fsync} to a non-@code{nil} value disables -this synchronization. Be careful---this means increased risk of data -loss. - -@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 buffer -contents remain unchanged---the modification you were trying to make -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 -displays 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 File Shadowing -@subsection Shadowing Files -@cindex shadow files -@cindex file shadows -@findex shadow-initialize - -@table @kbd -@item M-x shadow-initialize -Set up file shadowing. -@item M-x shadow-define-literal-group -Declare a single file to be shared between sites. -@item M-x shadow-define-regexp-group -Make all files that match each of a group of files be shared between hosts. -@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} -Define a shadow file cluster @var{name}. -@item M-x shadow-copy-files -Copy all pending shadow files. -@item M-x shadow-cancel -Cancel the instruction to shadow some files. -@end table - -You can arrange to keep identical @dfn{shadow} copies of certain files -in more than one place---possibly on different machines. To do this, -first you must set up a @dfn{shadow file group}, which is a set of -identically-named files shared between a list of sites. The file -group is permanent and applies to further Emacs sessions as well as -the current one. Once the group is set up, every time you exit Emacs, -it will copy the file you edited to the other files in its group. You -can also do the copying without exiting Emacs, by typing @kbd{M-x -shadow-copy-files}. - -To set up a shadow file group, use @kbd{M-x -shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. -See their documentation strings for further information. - -Before copying a file to its shadows, Emacs asks for confirmation. -You can answer ``no'' to bypass copying of this file, this time. If -you want to cancel the shadowing permanently for a certain file, use -@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. - -A @dfn{shadow cluster} is a group of hosts that share directories, so -that copying to or from one of them is sufficient to update the file -on all of them. Each shadow cluster has a name, and specifies the -network address of a primary host (the one we copy files to), and a -regular expression that matches the host names of all the other hosts -in the cluster. You can define a shadow cluster with @kbd{M-x -shadow-define-cluster}. - -@node Time Stamps -@subsection Updating Time Stamps Automatically -@cindex time stamps -@cindex modification dates -@cindex locale, date format - -You can arrange to put a time stamp in a file, so that it will be updated -automatically each time you edit and save the file. The time stamp -has to be in the first eight lines of the file, and you should -insert it like this: - -@example -Time-stamp: <> -@end example - -@noindent -or like this: - -@example -Time-stamp: " " -@end example - -@findex time-stamp - Then add the hook function @code{time-stamp} to the hook -@code{before-save-hook}; that hook function will automatically update -the time stamp, inserting the current date and time when you save the -file. You can also use the command @kbd{M-x time-stamp} to update the -time stamp manually. For other customizations, see the Custom group -@code{time-stamp}. Note that non-numeric fields in the time stamp are -formatted according to your locale setting (@pxref{Environment}). - -@node Reverting -@section Reverting a Buffer -@findex revert-buffer -@cindex drastic changes -@cindex reread a file - - 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} tries to position point in such a way that, if -the file was edited only slightly, you will be at approximately the -same piece of text after reverting as before. However, if you have made -drastic changes, point may wind up in 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.) - -@cindex Global Auto-Revert mode -@cindex mode, Global Auto-Revert -@cindex Auto-Revert mode -@cindex mode, Auto-Revert -@findex global-auto-revert-mode -@findex auto-revert-mode -@findex auto-revert-tail-mode - - You may find it useful to have Emacs revert files automatically when -they change. Three minor modes are available to do this. - - @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode, -which periodically checks all file buffers and reverts when the -corresponding file has changed. @kbd{M-x auto-revert-mode} enables a -local version, Auto-Revert mode, which applies only to the current -buffer. - - You can use Auto-Revert mode to ``tail'' a file such as a system -log, so that changes made to that file by other programs are -continuously displayed. To do this, just move the point to the end of -the buffer, and it will stay there as the file contents change. -However, if you are sure that the file will only change by growing at -the end, use Auto-Revert Tail mode instead -(@code{auto-revert-tail-mode}). It is more efficient for this. - -@vindex auto-revert-interval - The variable @code{auto-revert-interval} controls how often to check -for a changed file. Since checking a remote file is too slow, these -modes do not check or revert remote files. - - @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that -visit files under version control. - -@ifnottex -@include arevert-xtra.texi -@end ifnottex - -@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, it considers -each buffer, and each is auto-saved if auto-saving is enabled 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 rear of buffer name, then -adding digits and letters at the end for uniqueness. For -example, the @samp{*mail*} buffer in which you compose messages to be -sent might be auto-saved in a file named @file{#*mail*#704juu}. 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. - -@cindex auto-save for remote files -@vindex auto-save-file-name-transforms - The variable @code{auto-save-file-name-transforms} allows a degree -of control over the auto-save file name. It lets you specify a series -of regular expressions and replacements to transform the auto save -file name. The default value puts the auto-save files for remote -files (@pxref{Remote Files}) into the temporary file directory on the -local machine. - - 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-mode}. - -@vindex auto-save-visited-file-name - If you want auto-saving to be done in the visited file rather than -in a separate auto-save file, set the variable -@code{auto-save-visited-file-name} to a non-@code{nil} value. In this -mode, there is no real 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. (You can inhibit this by setting 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. Emacs doesn't accept values that are -too small: if you customize @code{auto-save-interval} to a value less -than 20, Emacs will behave as if the value is 20. - -@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 - Emacs records information about interrupted sessions for later -recovery in files named -@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. All -of this name except the @file{@var{pid}-@var{hostname}} part comes -from the value of @code{auto-save-list-file-prefix}. You can record -sessions in a different place by customizing that variable. 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 -@cindex symbolic links (visiting) -@cindex hard links (visiting) - - 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. - -@vindex find-file-existing-other-name -@vindex find-file-suppress-same-file-warnings - - Normally, if you visit a file which Emacs is already visiting under -a different name, Emacs displays a message in the echo area and uses -the existing buffer visiting that file. This can happen on systems -that support hard or symbolic links, or if you use a long file name on -a system that truncates long file names, or on a case-insensitive file -system. You can suppress the message by setting the variable -@code{find-file-suppress-same-file-warnings} to a non-@code{nil} -value. You can disable this feature entirely by setting the variable -@code{find-file-existing-other-name} to @code{nil}: then if you visit -the same file under two different names, you get a separate buffer for -each file name. - -@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 different version control systems---currently, it supports CVS, -GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU -project distributes CVS, GNU Arch, and RCS; we recommend that you use -either CVS or GNU Arch for your projects, and RCS for individual -files. We also have free software to replace SCCS, known as CSSC; if -you are using SCCS and don't want to make the incompatible change to -RCS or CVS, you can switch to CSSC. - - VC is enabled by default in Emacs. To disable it, set the -customizable variable @code{vc-handled-backends} to @code{nil} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex - - -@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. -@ifnottex -* Remote Repositories:: Efficient access to remote CVS servers. -* 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 ifnottex -@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 -* Why Version Control?:: Understanding the problems it addresses -* Version Systems:: Supported version control back-end systems. -* VC Concepts:: Words and concepts related to version control. -* Types of Log File:: The per-file VC log in contrast to the ChangeLog. -@end menu - -@node Why Version Control? -@subsubsection Understanding the problems it addresses - - Version control systems provide you with three important capabilities: -reversibility, concurrency, and history. - - The most basic capability you get from a version-control system is -reversibility, the ability to back up to a saved, known-good state when -you discover that some modification you did was a mistake or a bad idea. - - Version-control systems also support concurrency, the ability to -have many people modifying the same collection of code or documents -knowing that conflicting modifications can be detected and resolved. - - Version-control systems give you the capability to attach a history -to your data, explanatory comments about the intention behind each -change to it. Even for a programmer working solo change histories -are an important aid to memory; for a multi-person project they -become a vitally important form of communication among developers. - -@node Version Systems -@subsubsection Supported Version Control Systems - -@cindex back end (version control) - VC currently works with six different version control systems or -``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. - -@cindex CVS - CVS is a free version control system that is used for the majority -of free software projects today. It allows concurrent multi-user -development either locally or over the network. Some of its -shortcomings, corrected by newer systems such as GNU Arch, are that it -lacks atomic commits or support for renaming files. VC supports all -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 GNU Arch -@cindex Arch - GNU Arch is a new version control system that is designed for -distributed work. It differs in many ways from old well-known -systems, such as CVS and RCS. It supports different transports for -interoperating between users, offline operations, and it has good -branching and merging features. It also supports atomic commits, and -history of file renaming and moving. VC does not support all -operations provided by GNU Arch, so you must sometimes invoke it from -the command line, or use a specialized module. - -@cindex RCS - RCS is the free version control system around which VC was initially -built. The VC commands are therefore conceptually closest to RCS. -Almost everything you can do with RCS can be done through VC. You -cannot use RCS over the network though, and it only works at the level -of individual files, rather than projects. You should use it if you -want a simple, yet reliable tool for handling individual files. - -@cindex SVN -@cindex Subversion - Subversion is a free version control system designed to be similar -to CVS but without CVS's problems. Subversion supports atomic commits, -and versions directories, symbolic links, meta-data, renames, copies, -and deletes. It can be used via http or via its own protocol. - -@cindex MCVS -@cindex Meta-CVS - Meta-CVS is another attempt to solve problems arising in CVS. It -supports directory structure versioning, improved branching and -merging, and use of symbolic links and meta-data in repositories. - -@cindex SCCS - SCCS is a proprietary but widely used version control system. In -terms of capabilities, it is the weakest of the six 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. Since SCCS is -non-free, not respecting its users freedom, you should not use it; -use its free replacement CSSC instead. But you should use CSSC only -if for some reason you cannot use RCS, or one of the higher-level -systems such as CVS or GNU Arch. - -In the following, we discuss mainly RCS, SCCS and CVS. Nearly -everything said about CVS applies to GNU Arch, Subversion and Meta-CVS -as well. - -@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. - - To go beyond these basic concepts, you will need to understand three -ways in which version-control systems can differ from each other. They -can be locking or merging; they can be file-based or changeset-based; -and they can be centralized or decentralized. VC handles all these -choices, but they lead to differing behaviors which you will need -to understand as you use it. - -@cindex locking versus merging - 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). In a locking -system, such as SCCS, you must @dfn{lock} a file before you start to -edit it. The other method is @dfn{merging}; the system tries 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. - - By contrast, a merging system lets each user check out and modify a -work file at any time. When you check in a a file, the system will -attempt to merge your changes with any others checked into the -repository since you checked out the file. - - Both locking and merging systems can have problems when multiple users -try to modify the same file at the same time. Locking systems have -@dfn{lock conflicts}; a user may try to check a file out and be unable -to because it is locked. In merging systems, @dfn{merge conflicts} -happen when you check in a change to a file that conflicts with a change -checked in by someone else after your checkout. Both kinds of conflict -have to be resolved by human judgment and communication. - - SCCS always uses locking. RCS is lock-based by default but can be told -to operate in a merging style. CVS is merge-based by default but can -be told to operate in a locking mode. Most later version-control -systems, such as Subversion and GNU Arch, have been fundamentally -merging-based rather than locking-based. This is because experience -has shown that the merging-based approach is generally superior to -the locking one, both in convenience to developers and in minimizing -the number and severity of conflicts that actually occur. - - While it is rather unlikely that anyone will ever again build a -fundamentally locking-based rather than merging-based version-control -system in the future, merging-based version-systems sometimes have locks -retrofitted onto them for reasons having nothing to do with technology. -@footnote{Usually the control-freak instincts of managers.} For this -reason, and to support older systems still in use, VC mode supports -both locking and merging version control and tries to hide the differences -between them as much as possible. - -@cindex files versus changesets. - On SCCS, RCS, CVS, and other early version-control systems, checkins -and other operations are @dfn{file-based}; each file has its own -@dfn{master file} with its own comment- and revision history separate -from that of all other files in the system. Later systems, beginning -with Subversion, are @dfn{changeset-based}; a checkin may include -changes to several files and that change set is treated as a unit by the -system. Any comment associated with the change doesn't belong to any -one file, but is attached to the changeset itself. - - Changeset-based version control is in general both more flexible and -more powerful than file-based version control; usually, when a change to -multiple files has to be backed out, it's good to be able to easily -identify and remove all of it. - -@cindex centralized vs. decentralized - Early version-control systems were designed around a @dfn{centralized} -model in which each project has only one repository used by all -developers. SCCS, RCS, CVS, and Subversion share this kind of model. -It has two important problems. One is that a single repository is a -single point of failure---if the repository server is down all work -stops. The other is that you need to be connected live to the server to -do checkins and checkouts; if you're offline, you can't work. - - Newer version-control systems like GNU Arch are @dfn{decentralized}. -A project may have several different repositories, and these systems -support a sort of super-merge between repositories that tries to -reconcile their change histories. At the limit, each developer has -his/her own repository, and repository merges replace checkin/commit -operations. - - VC's job is to help you manage the traffic between your personal -workfiles and a repository. Whether that repository is a single master -or one of a network of peer repositories is not something VC has to care -about. Thus, the difference between a centralized and a decentralized -version-control system is invisible to VC mode. - -@iftex -(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{CVS Options}). -@end ifnottex - - -@node Types of Log File -@subsubsection Types of Log File -@cindex types of log file -@cindex log File, types of -@cindex version control log - - Projects that use a revision control system can have @emph{two} -types of log for changes. One is the per-file log maintained by the -revision control system: each time you check in a change, you must -fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This -kind of log is called the @dfn{version control log}, also the -@dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}. - - The other kind of log is the file @file{ChangeLog} (@pxref{Change -Log}). It provides a chronological record of all changes to a large -portion of a program---typically one directory and its subdirectories. -A small program would use one @file{ChangeLog} file; a large program -may well merit a @file{ChangeLog} file in each major directory. -@xref{Change Log}. - - A project maintained with version control can use just the per-file -log, or it can use both kinds of logs. It can handle some files one -way and some files the other way. Each project has its policy, which -you should follow. - - When the policy is to use both, you typically want to write an entry -for each change just once, then put it into both logs. You can write -the entry in @file{ChangeLog}, then copy it to the log buffer when you -check in the change. Or you can write the entry in the log buffer -while checking in the change, and later use the @kbd{C-x v a} command -to copy it to @file{ChangeLog} -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex - - -@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}. - -@vindex auto-revert-check-vc-info - When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is -under version control, it updates the version control information in -the mode line. However, Auto Revert mode may not properly update this -information if the version control status changes without changes to -the work file, from outside the current Emacs session. If you set -@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates -the version control status information every -@code{auto-revert-interval} seconds, even if the work file itself is -unchanged. The resulting CPU usage depends on the version control -system, but is usually not excessive. - -@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 -@itemx C-x v v -Perform the next logical version control operation on this file. -@end table - -@findex vc-next-action -@kindex 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. - -@findex vc-toggle-read-only -@kindex C-x C-q @r{(Version Control)} - As a special convenience that is particularly useful for files with -locking, you can let Emacs check a file in or out whenever you change -its read-only flag. This means, for example, that you cannot -accidentally edit a file without properly checking it out first. To -achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only} -in your @file{~/.emacs} file. (@xref{Init Rebinding}.) - -@menu -* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. -* Without Locking:: Without locking: default mode for CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. -* 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 v v} can either lock a file or check it in: - -@itemize @bullet -@item -If the file is not locked, @kbd{C-x v v} 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 v v} 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 v v} releases the lock and makes the file read-only -again. - -@item -If the file is locked by some other user, @kbd{C-x v v} 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 v v} 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. You must do this before you can check in your own changes. (To -pick up any recent changes from the master file @emph{without} trying -to commit your own changes, type @kbd{C-x v m @key{RET}}.) -@xref{Merging}. - -@item -If there are no new changes in the master file, but you have made -modifications in your work file, @kbd{C-x v v} 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 v v} 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 that 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 v v} with an unmodified file locks the -file, just as it does with RCS in its normal (locking) mode. - -@node Advanced C-x v v -@subsubsection Advanced Control in @kbd{C-x v v} - -@cindex version number to check in/out - When you give a prefix argument to @code{vc-next-action} (@kbd{C-u -C-x v v}), it still performs the next logical version control -operation, but accepts additional arguments to specify precisely how -to do the operation. - -@itemize @bullet -@item -If the file is modified (or locked), you can specify the version -number to use for the new version that you check in. This is one way -to create a new branch (@pxref{Branches}). - -@item -If the file is not modified (and unlocked), you can specify the -version to select; this lets you start working from an older version, -or on another branch. If you do not enter any version, that takes you -to the highest version on the current branch; therefore @kbd{C-u C-x -v v @key{RET}} is a convenient way to get the latest version of a file from -the repository. - -@item -@cindex specific version control system -Instead of the version number, you can also specify the name of a -version control system. This is useful when one file is being managed -with two version control systems at the same time -@iftex -(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs -Features}). -@end iftex -@ifnottex -(@pxref{Local Version Control}). -@end ifnottex - -@end itemize - -@node Log Buffer -@subsubsection Features of the Log Entry Buffer - - When you check in changes, @kbd{C-x v v} first reads a log entry. It -pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. - - Sometimes the @samp{*VC-Log*} buffer contains default text when you enter it, -typically the last log message entered. If it does, mark and point -are set around the entire contents of the buffer so that it is easy to -kill the contents of the buffer with @kbd{C-w}. - -@findex log-edit-insert-changelog - If you work by writing entries in the @file{ChangeLog} -(@pxref{Change Log}) and then commit the change under revision -control, you can generate the Log Edit text from the ChangeLog using -@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for -entries for the file(s) concerned in the top entry in the ChangeLog -and uses those paragraphs as the log text. This text is only inserted -if the top entry was made under your user name on the current date. -@iftex -@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Change Logs and VC}, -@end ifnottex -for the opposite way of working---generating ChangeLog entries from -the revision control log. - - In the @samp{*VC-Log*} buffer, @kbd{C-c C-f} (@kbd{M-x -log-edit-show-files}) shows the list of files to be committed in case -you need to check that. (This can be a list of more than one file if -you use VC Dired mode or PCL-CVS. -@iftex -@xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{VC Dired Mode}, -@end ifnottex -and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs -Front-End to CVS}.) - - When you have finished editing the log message, type @kbd{C-c C-c} to -exit the buffer and commit the change. - - 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 master version from which -you started editing. - -@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 file with per-line version information and using colors. -@end table - -@findex vc-version-other-window -@kindex C-x v ~ - To examine an old version in its entirety, 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 = - It is usually 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 master version from which you started editing the -file (this is not necessarily the latest 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. -Both forms display the output in a special buffer in another window. - - 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 -@iftex -(@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features}) -@end iftex -@ifnottex -(@pxref{Snapshots}) -@end ifnottex -instead of one or both version numbers. - - 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. - -@vindex vc-diff-switches -@vindex vc-rcs-diff-switches - @kbd{C-x v =} works by running a variant of the @code{diff} utility -designed to work with the version control system in use. When you -invoke @code{diff} this way, in addition to the options specified by -@code{diff-switches} (@pxref{Comparing Files}), it receives those -specified by @code{vc-diff-switches}, plus those specified for the -specific back end by @code{vc-@var{backend}-diff-switches}. For -instance, when the version control back end is RCS, @code{diff} uses -the options in @code{vc-rcs-diff-switches}. The -@samp{vc@dots{}diff-switches} variables are @code{nil} by default. - - The buffer produced by @kbd{C-x v =} supports the commands of -Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and -@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always -find the corresponding locations in the current work file. (Older -versions are not, in general, present as files on your disk.) - -@findex vc-annotate -@kindex C-x v g - For some back ends, you can display the file @dfn{annotated} with -per-line version information and using colors to enhance the visual -appearance, with the command @kbd{M-x vc-annotate}. It creates a new -buffer (the ``annotate buffer'') displaying the file's text, with each -part colored to show how old it is. Text colored red is new, blue means -old, and intermediate colors indicate intermediate ages. By default, -the color is scaled over the full range of ages, such that the oldest -changes are blue, and the newest changes are red. - - When you give a prefix argument to this command, it uses the -minibuffer to read two arguments: which version number to display and -annotate (instead of the current file contents), and the time span in -days the color range should cover. - - From the annotate buffer, these and other color scaling options are -available from the @samp{VC-Annotate} menu. In this buffer, you can -also use the following keys to browse the annotations of past revisions, -view diffs, or view log entries: - -@table @kbd -@item P -Annotate the previous revision, that is to say, the revision before -the one currently annotated. A numeric prefix argument is a repeat -count, so @kbd{C-u 10 P} would take you back 10 revisions. - -@item N -Annotate the next revision---the one after the revision currently -annotated. A numeric prefix argument is a repeat count. - -@item J -Annotate the revision indicated by the current line. - -@item A -Annotate the revision before the one indicated by the current line. -This is useful to see the state the file was in before the change on -the current line was made. - -@item D -Display the diff between the current line's revision and the previous -revision. This is useful to see what the current line's revision -actually changed in the file. - -@item L -Show the log of the current line's revision. This is useful to see -the author's description of the changes in the revision on the current -line. - -@item W -Annotate the workfile version--the one you are editing. If you used -@kbd{P} and @kbd{N} to browse to other revisions, use this key to -return to your current version. -@end table - -@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:: Canceling changes before or after check-in. -@ifnottex -* VC Dired Mode:: Listing files managed by version control. -* VC Dired Commands:: Commands to use in a VC Dired buffer. -@end ifnottex -@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 - - To register the file, Emacs must choose which version control system -to use for it. If the file's directory already contains files -registered in a version control system, Emacs uses that system. If -there is more than one system in use for a directory, Emacs uses the -one that appears first in @code{vc-handled-backends} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex -On the other hand, if there are no files already registered, Emacs uses -the first system from @code{vc-handled-backends} that could register -the file (for example, you cannot register a file under CVS if its -directory is not already part of a CVS tree); with the default value -of @code{vc-handled-backends}, this means that Emacs uses RCS in this -situation. - - If locking is in use, @kbd{C-x v i} leaves the file unlocked and -read-only. Type @kbd{C-x v v} 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 v v}. Until you do that, the version -appears as @samp{@@@@} in the mode line. - -@vindex vc-default-init-version -@cindex initial version number to register - 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. The point is centered at the -revision of the file that is currently being visited. - - In the change log buffer, you can use the following keys to move -between the logs of revisions and of files, to view past revisions, and -to view diffs: - -@table @kbd -@item p -Move to the previous revision-item in the buffer. (Revision entries in the log -buffer are usually in reverse-chronological order, so the previous -revision-item usually corresponds to a newer revision.) A numeric -prefix argument is a repeat count. - -@item n -Move to the next revision-item (which most often corresponds to the -previous revision of the file). A numeric prefix argument is a repeat -count. - -@item P -Move to the log of the previous file, when the logs of multiple files -are in the log buffer -@iftex -(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{VC Dired Mode}). -@end ifnottex -Otherwise, just move to the beginning of the log. A numeric prefix -argument is a repeat count, so @kbd{C-u 10 P} would move backward 10 -files. - -@item N -Move to the log of the next file, when the logs of multiple files are -in the log buffer -@iftex -(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{VC Dired Mode}). -@end ifnottex -It also takes a numeric prefix argument as a repeat count. - -@item f -Visit the revision indicated at the current line, like typing @kbd{C-x -v ~} and specifying this revision's number (@pxref{Old Versions}). - -@item d -Display the diff (@pxref{Comparing Files}) between the revision -indicated at the current line and the next earlier revision. This is -useful to see what actually changed when the revision indicated on the -current line was committed. -@end table - -@node VC Undo -@subsubsection Undoing Version Control Actions - -@table @kbd -@item C-x v u -Revert the buffer and the file to the version from which you started -editing the file. - -@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 -version from which you started editing the file, 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 with respect to the master 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, but only if your work file corresponds -to that version---you cannot use @kbd{C-x v c} to cancel a version -that is not the latest on its branch. @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 -@iftex -(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Version Headers}). -@end ifnottex -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. - -@ifnottex -@c vc1-xtra.texi needs extra level of lowering. -@lowersections -@include vc1-xtra.texi -@raisesections -@end ifnottex - -@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 not supported for SCCS. - - 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 v v} 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 v v}, and make whatever changes you want. Then, -when you check in the changes, use @kbd{C-u C-x v v}. 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 v v}. 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 v v} 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 -v v}. 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 firsts asks you in the -minibuffer where the changes should come from. If you just type -@key{RET}, Emacs merges any changes that were made on the same branch -since you checked the file out (we call this @dfn{merging the news}). -This is the common way to pick up recent changes from the repository, -regardless of whether you have already changed the file yourself. - - You can also enter a branch number or a pair of version numbers in -the minibuffer. Then @kbd{C-x v m} finds the changes from that -branch, or the differences 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 v v -@key{RET}}. Version 1.5 is now current. If locking is used for the file, -type @kbd{C-x v v} to lock version 1.5 so that you can change it. Next, -type @kbd{C-x v m 1.3.1 @key{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. Don't forget to -check in the merged version afterwards. - -@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 -@iftex -(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Version Headers}). -@end ifnottex -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 v v} and specify the correct -branch number. This ensures that Emacs knows which branch it is using -during this particular editing session. - -@ifnottex -@include vc2-xtra.texi -@end ifnottex - -@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). Emacs also includes a directory browser -feature 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} displays 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 owners (like -@samp{ls -l}). - -@vindex list-directory-brief-switches -@vindex list-directory-verbose-switches - The text of a directory listing is mostly 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). - -@vindex directory-free-space-program -@vindex directory-free-space-args - In verbose directory listings, Emacs adds information about the -amount of free space on the disk that contains the directory. To do -this, it runs the program specified by -@code{directory-free-space-program} with arguments -@code{directory-free-space-args}. - -@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}. The value of @code{diff-switches} should be a -string; the default is @code{"-c"} to specify a context diff. -@xref{Top,, Diff, diff, Comparing and Merging Files}, for more -information about @command{diff} output formats. - -@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. (For more information -about windows in Emacs, @ref{Windows}.) Comparison starts at point in -each window, after pushing each initial point value on the mark ring -in its respective buffer. Then it moves point forward in each window, -one character at a time, until it reaches characters that don't match. -Then the command exits. - - If point in the two windows is followed by non-matching text when -the command starts, @kbd{M-x compare-windows} tries heuristically to -advance up to matching text in the two windows, and then exits. So if -you use @kbd{M-x compare-windows} repeatedly, each time it either -skips one matching range or finds the start of another. - -@vindex compare-ignore-case -@vindex compare-ignore-whitespace - With a numeric argument, @code{compare-windows} ignores changes in -whitespace. If the variable @code{compare-ignore-case} is -non-@code{nil}, the comparison ignores differences in case as well. -If the variable @code{compare-ignore-whitespace} is non-@code{nil}, -@code{compare-windows} normally ignores changes in whitespace, and a -prefix argument turns that off. - -@cindex Smerge mode -@findex smerge-mode -@cindex failed merges -@cindex merges, failed -@cindex comparing 3 files (@code{diff3}) - You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor -mode for editing output from the @command{diff3} program. This is -typically the result of a failed merge from a version control system -``update'' outside VC, due to conflicting changes to a file. Smerge -mode provides commands to resolve conflicts by selecting specific -changes. - -@iftex -@xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Emerge}, -@end ifnottex -for the Emerge facility, which provides a powerful interface for -merging files. - -@node Diff Mode -@section Diff Mode -@cindex Diff mode -@findex diff-mode -@cindex patches, editing - - Diff mode is used for the output of @kbd{M-x diff}; it is also -useful for editing patches and comparisons produced by the -@command{diff} program. To select Diff mode manually, type @kbd{M-x -diff-mode}. - - One general feature of Diff mode is that manual edits to the patch -automatically correct line numbers, including those in the hunk -header, so that you can actually apply the edited patch. Diff mode -treats each hunk location as an ``error message,'' so that you can use -commands such as @kbd{C-x '} to visit the corresponding source -locations. It also provides the following commands to navigate, -manipulate and apply parts of patches: - -@table @kbd -@item M-n -Move to the next hunk-start (@code{diff-hunk-next}). - -@item M-p -Move to the previous hunk-start (@code{diff-hunk-prev}). - -@item M-@} -Move to the next file-start, in a multi-file patch -(@code{diff-file-next}). - -@item M-@{ -Move to the previous file-start, in a multi-file patch -(@code{diff-file-prev}). - -@item M-k -Kill the hunk at point (@code{diff-hunk-kill}). - -@item M-K -In a multi-file patch, kill the current file part. -(@code{diff-file-kill}). - -@item C-c C-a -Apply this hunk to its target file (@code{diff-apply-hunk}). With a -prefix argument of @kbd{C-u}, revert this hunk. - -@item C-c C-c -Go to the source corresponding to this hunk (@code{diff-goto-source}). - -@item C-c C-e -Start an Ediff session with the patch (@code{diff-ediff-patch}). -@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. - -@item C-c C-n -Restrict the view to the current hunk (@code{diff-restrict-view}). -@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the -view to the current patch of a multiple file patch. To widen again, -use @kbd{C-x n w}. - -@item C-c C-r -Reverse the direction of comparison for the entire buffer -(@code{diff-reverse-direction}). - -@item C-c C-s -Split the hunk at point (@code{diff-split-hunk}). This is for -manually editing patches, and only works with the unified diff format. - -@item C-c C-u -Convert the entire buffer to unified format -(@code{diff-context->unified}). With a prefix argument, convert -unified format to context format. In Transient Mark mode, when the -mark is active, this command operates only on the region. - -@item C-c C-w -Refine the current hunk so that it disregards changes in whitespace -(@code{diff-refine-hunk}). -@end table - - @kbd{C-x 4 a} in Diff mode operates on behalf of the target file, -but gets the function name from the patch itself. @xref{Change Log}. -This is useful for making log entries for functions that are deleted -by the patch. - -@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 minor mode called View -mode. - - A related command, @kbd{M-x view-buffer}, views a buffer already present -in Emacs. @xref{Misc Buffer}. - -@kindex C-x i -@findex insert-file - @kbd{M-x insert-file} (also @kbd{C-x i}) 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 insert-file-literally - @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, -except the file is inserted ``literally'': it is treated as a sequence -of @acronym{ASCII} characters with no special encoding or conversion, -similar to the @kbd{M-x find-file-literally} command -(@pxref{Visiting}). - -@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}. The variable -@code{write-region-inhibit-fsync} applies to these commands, as well -as saving files; see @ref{Customize Save}. - -@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 the file name -@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. - - If the argument @var{new} is just a directory name, the real new -name is in that directory, with the same non-directory component as -@var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} -renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all -the remaining commands in this section. All of them ask for -confirmation when the new file name already exists, too. - -@findex add-name-to-file -@cindex hard links (creation) - 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 is created as a ``hard link'' to the existing file. -The new name must belong on the same file system that the file is on. -On MS-Windows, this command works only if the file resides in an NTFS -file system. On MS-DOS, it works by copying the file. - -@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. - -@findex make-symbolic-link -@cindex symbolic links (creation) - @kbd{M-x make-symbolic-link} reads two file names @var{target} and -@var{linkname}, then creates a symbolic link named @var{linkname}, -which points 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 nonexistent 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. - - Not all systems support symbolic links; on systems that don't -support them, this command is not defined. - -@node Compressed Files -@section Accessing Compressed Files -@cindex compression -@cindex uncompression -@cindex Auto Compression mode -@cindex mode, Auto Compression -@pindex gzip - - Emacs automatically uncompresses compressed files when you visit -them, and automatically recompresses them if you alter them and save -them. 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. - -@findex auto-compression-mode -@vindex auto-compression-mode - To disable this feature, type the command @kbd{M-x -auto-compression-mode}. You can disable it permanently by -customizing the variable @code{auto-compression-mode}. - -@node File Archives -@section File Archives -@cindex mode, tar -@cindex Tar mode -@cindex file archives - - A file whose name ends in @samp{.tar} is normally an @dfn{archive} -made by the @code{tar} program. Emacs views these files in a special -mode called Tar mode which provides a Dired-like list of the contents -(@pxref{Dired}). You can move around through the list just as you -would in Dired, and visit the subfiles contained in the archive. -However, not all Dired commands are available in Tar mode. - - If Auto Compression mode is enabled (@pxref{Compressed Files}), then -Tar mode is used also for compressed archives---files with extensions -@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. - - The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file -into its own buffer. You can edit it there, and if you save the -buffer, the edited version will replace the version in the Tar buffer. -@kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts -the file and displays it in another window, so you could edit the file -and operate on the archive simultaneously. @kbd{d} marks a file for -deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in -Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} -renames a file within the archive. @kbd{g} reverts the buffer from -the archive on disk. - - The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission -bits, group, and owner, respectively. - - If your display supports colors and the mouse, moving the mouse -pointer across a file name highlights that file name, indicating that -you can click on it. Clicking @kbd{Mouse-2} on the highlighted file -name extracts the file into a buffer and displays that buffer. - - Saving the Tar buffer writes a new version of the archive to disk with -the changes you made to the components. - - You don't need the @code{tar} program to use Tar mode---Emacs reads -the archives directly. However, accessing compressed archives -requires the appropriate uncompression program. - -@cindex Archive mode -@cindex mode, archive -@cindex @code{arc} -@cindex @code{jar} -@cindex @code{zip} -@cindex @code{lzh} -@cindex @code{zoo} -@pindex arc -@pindex jar -@pindex zip -@pindex lzh -@pindex zoo -@cindex Java class archives -@cindex unzip archives - A separate but similar Archive mode is used for archives produced by -the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and -@code{zoo}, which have extensions corresponding to the program names. -Archive mode also works for those @code{exe} files that are -self-extracting executables. - - The key bindings of Archive mode are similar to those in Tar mode, -with the addition of the @kbd{m} key which marks a file for subsequent -operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. -Also, the @kbd{a} key toggles the display of detailed file -information, for those archive types where it won't fit in a single -line. Operations such as renaming a subfile, or changing its mode or -owner, are supported only for some of the archive formats. - - Unlike Tar mode, Archive mode runs the archiving program to unpack -and repack archives. Details of the program names and their options -can be set in the @samp{Archive} Customize group. However, you don't -need these programs to look at the archive table of contents, only to -extract or manipulate the subfiles in the archive. - -@node Remote Files -@section Remote Files - -@cindex Tramp -@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} -/@var{user}@@@var{host}#@var{port}:@var{filename} -/@var{method}:@var{user}@@@var{host}:@var{filename} -/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} -@end group -@end example - -@noindent -To carry out this request, Emacs uses either the FTP program or a -remote-login program such as @command{ssh}, @command{rlogin}, or -@command{telnet}. You can always specify in the file name which -method to use---for example, -@file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas -@file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}. -When you don't specify a method in the file name, Emacs chooses -the method as follows: - -@enumerate -@item -If the host name starts with @samp{ftp.} (with dot), then Emacs uses -FTP. -@item -If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses -FTP. -@item -Otherwise, Emacs uses @command{ssh}. -@end enumerate - -@noindent -Remote file access through FTP is handled by the Ange-FTP package, which -is documented in the following. Remote file access through the other -methods is handled by the Tramp package, which has its own manual. -@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. - -When the Ange-FTP package is used, Emacs 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}. The form using -@var{port} allows you to access servers running on a non-default TCP -port. - -@cindex backups for remote files -@vindex ange-ftp-make-backup-files - If you want to disable backups for remote files, set the variable -@code{ange-ftp-make-backup-files} to @code{nil}. - - By default, the auto-save files (@pxref{Auto Save Files}) for remote -files are made in the temporary file directory on the local machine. -This is achieved using the variable @code{auto-save-file-name-transforms}. - -@cindex ange-ftp -@vindex ange-ftp-default-user -@cindex user name for remote file access - 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. - -@cindex anonymous FTP -@vindex ange-ftp-generate-anonymous-password - To visit files accessible by anonymous FTP, you use special user -names @samp{anonymous} or @samp{ftp}. Passwords for these user names -are handled specially. The variable -@code{ange-ftp-generate-anonymous-password} controls what happens: if -the value of this variable is a string, then that string is used as -the password; if non-@code{nil} (the default), then the value of -@code{user-mail-address} is used; if @code{nil}, then Emacs prompts -you for a password as usual. - -@cindex firewall, and accessing remote files -@cindex gateway, and remote file access with @code{ange-ftp} -@vindex ange-ftp-smart-gateway -@vindex ange-ftp-gateway-host - Sometimes you may be unable to access files on a remote machine -because a @dfn{firewall} in between blocks the connection for security -reasons. If you can log in on a @dfn{gateway} machine from which the -target files @emph{are} accessible, and whose FTP server supports -gatewaying features, you can still use remote file names; all you have -to do is specify the name of the gateway machine by setting the -variable @code{ange-ftp-gateway-host}, and set -@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able -to make remote file names work, but the procedure is complex. You can -read the instructions by typing @kbd{M-x finder-commentary @key{RET} -ange-ftp @key{RET}}. - -@vindex file-name-handler-alist -@cindex disabling remote files - You can entirely turn off the FTP file name feature by removing the -entries @code{ange-ftp-completion-hook-function} and -@code{ange-ftp-hook-function} from the variable -@code{file-name-handler-alist}. You can turn off the feature in -individual cases by quoting the file name with @samp{/:} (@pxref{Quoted -File Names}). - -@node Quoted File Names -@section Quoted File Names - -@cindex quoting file names -@cindex file names, quote special characters - 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}. - - Quoting with @samp{/:} is also a way to enter in the minibuffer a -file name that contains @samp{$}. In order for this to work, the -@samp{/:} must be at the beginning of the minibuffer contents. (You -can also double each @samp{$}; see @ref{File Names with $}.) - - You can also quote wildcard characters with @samp{/:}, for visiting. -For example, @file{/:/tmp/foo*bar} visits the file -@file{/tmp/foo*bar}. - - Another method of getting the same result is to enter -@file{/tmp/foo[*]bar}, which is a wildcard specification that matches -only @file{/tmp/foo*bar}. However, in many cases there is no need to -quote the wildcard characters because even unquoted they give the -right result. 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 only -@file{/tmp/foo*bar}. - -@node File Name Cache -@section File Name Cache - -@cindex file name caching -@cindex cache of file names -@pindex find -@kindex C-@key{TAB} -@findex file-cache-minibuffer-complete - You can use the @dfn{file name cache} to make it easy to locate a -file by name, without having to remember exactly where it is located. -When typing a file name in the minibuffer, @kbd{C-@key{tab}} -(@code{file-cache-minibuffer-complete}) completes it using the file -name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the -possible completions of what you had originally typed. (However, note -that the @kbd{C-@key{tab}} character cannot be typed on most text-only -terminals.) - - The file name cache does not fill up automatically. Instead, you -load file names into the cache using these commands: - -@findex file-cache-add-directory -@table @kbd -@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} to the file name cache. -@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache. -@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache, using @command{locate} to find -them all. -@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} -Add each file name in each directory listed in @var{variable} -to the file name cache. @var{variable} should be a Lisp variable -such as @code{load-path} or @code{exec-path}, whose value is a list -of directory names. -@item M-x file-cache-clear-cache @key{RET} -Clear the cache; that is, remove all file names from it. -@end table - - The file name cache is not persistent: it is kept and maintained -only for the duration of the Emacs session. You can view the contents -of the cache with the @code{file-cache-display} command. - -@node File Conveniences -@section Convenience Features for Finding Files - - In this section, we introduce some convenient facilities for finding -recently-opened files, reading file names from a buffer, and viewing -image files. - -@findex recentf-mode -@vindex recentf-mode -@findex recentf-save-list -@findex recentf-edit-list - If you enable Recentf mode, with @kbd{M-x recentf-mode}, the -@samp{File} menu includes a submenu containing a list of recently -opened files. @kbd{M-x recentf-save-list} saves the current -@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} -edits it. - - The @kbd{M-x ffap} command generalizes @code{find-file} with more -powerful heuristic defaults (@pxref{FFAP}), often based on the text at -point. Partial Completion mode offers other features extending -@code{find-file}, which can be used with @code{ffap}. -@xref{Completion Options}. - -@findex image-mode -@findex image-toggle-display -@cindex images, viewing - Visiting image files automatically selects Image mode. This major -mode allows you to toggle between displaying the file as an image in -the Emacs buffer, and displaying its underlying text representation, -using the command @kbd{C-c C-c} (@code{image-toggle-display}). This -works only when Emacs can display the specific image type. If the -displayed image is wider or taller than the frame, the usual point -motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts -of the image to be displayed. - -@findex thumbs-mode -@findex mode, thumbs - See also the Image-Dired package (@pxref{Image-Dired}) for viewing -images as thumbnails. - -@node Filesets -@section Filesets -@cindex filesets - -@findex filesets-init - If you regularly edit a certain group of files, you can define them -as a @dfn{fileset}. This lets you perform certain operations, such as -visiting, @code{query-replace}, and shell commands on all the files -at once. To make use of filesets, you must first add the expression -@code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). -This adds a @samp{Filesets} menu to the menu bar. - -@findex filesets-add-buffer -@findex filesets-remove-buffer - The simplest way to define a fileset is by adding files to it one -at a time. To add a file to fileset @var{name}, visit the file and -type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If -there is no fileset @var{name}, this creates a new one, which -initially creates only the current file. The command @kbd{M-x -filesets-remove-buffer} removes the current file from a fileset. - - You can also edit the list of filesets directly, with @kbd{M-x -filesets-edit} (or by choosing @samp{Edit Filesets} from the -@samp{Filesets} menu). The editing is performed in a Customize buffer -(@pxref{Easy Customization}). Filesets need not be a simple list of -files---you can also define filesets using regular expression matching -file names. Some examples of these more complicated filesets are -shown in the Customize buffer. Remember to select @samp{Save for -future sessions} if you want to use the same filesets in future Emacs -sessions. - - You can use the command @kbd{M-x filesets-open} to visit all the -files in a fileset, and @kbd{M-x filesets-close} to close them. Use -@kbd{M-x filesets-run-cmd} to run a shell command on all the files in -a fileset. These commands are also available from the @samp{Filesets} -menu, where each existing fileset is represented by a submenu. - -@ignore - arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 -@end ignore