@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,99, 2000, 2001
+@c Copyright (C) 1985,86,87,93,94,95,97,99, 2000, 2001, 2004
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Files, Buffers, Fixit, Top
+@node Files, Buffers, Keyboard Macros, Top
@chapter File Handling
@cindex files
@code{substitute-in-file-name}. The substitution is performed only on
file names read as such using the minibuffer.
- You can include non-ASCII characters in file names if you set the
+ 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{Specify Coding}.
system. @xref{Frames}.
@findex find-file-literally
- If you wish to edit a file as a sequence of ASCII characters with no special
+ 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
@xref{Interlocking,, Simultaneous Editing}.
@vindex require-final-newline
- If the value of the variable @code{require-final-newline} is @code{t},
-Emacs silently puts a newline at the end of any file that doesn't
-already end in one, every time a file is saved or written. 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}.
+ If the value of the variable @code{require-final-newline} is
+@code{t}, Emacs silently puts a newline at the end of any file that
+doesn't already end in one, every time a file is saved or written. 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.
@menu
* Backup:: How Emacs saves the old version of your file.
default, both variables are 2.
@vindex delete-old-versions
- If @code{delete-old-versions} is non-@code{nil}, 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 @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}.
or like this:
@example
-Time-stamp: ""
+Time-stamp: " "
@end example
Then add the hook function @code{time-stamp} to the hook
-@code{write-file-functions}; that hook function will automatically update
+@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
the current buffer. Since reverting a buffer unintentionally could lose
a lot of work, you must confirm this command with @kbd{yes}.
- @code{revert-buffer} keeps point at the same distance (measured in
-characters) from the beginning of the file. If the file was edited only
-slightly, you will be at approximately the same piece of text after
-reverting as before. If you have made drastic changes, the same value of
-point in the old file may address a totally different piece of text.
+ @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.
Auto-Revert mode, Emacs periodically checks all file buffers and
reverts any when the corresponding file has changed. The local
variant, Auto-Revert mode, applies only to buffers in which it was
-activated. Checking the files is done at intervals determined by the
-variable @code{auto-revert-interval}.
+activated. 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.
@node Auto Save
@section Auto-Saving: Protection Against Disasters
@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 auto-saved in a file named @file{#*mail*#704juu}. Auto-save file
+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
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}.
+auto-save-mode}.
@vindex auto-save-visited-file-name
If you want auto-saving to be done in the visited file rather than
@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
If you visit two names for the same file, normally Emacs makes
two different buffers, but it warns you about the situation.
-@vindex find-file-existing-other-name
+@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
@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
+such as the creation time of each version, who created it, and a
description of what was changed in that version.
The Emacs version control interface is called VC. Its commands work
-with three version control systems---RCS, CVS, and SCCS. The GNU
-project recommends RCS and CVS, which are free software and available
-from the Free Software Foundation. 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.
+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}
+(@pxref{Customizing VC}).
@menu
* Introduction to VC:: How version control works in general.
@node Version Systems
@subsubsection Supported Version Control Systems
-@cindex RCS
@cindex back end (version control)
- VC currently works with three different version control systems or
-``back ends'': RCS, CVS, and SCCS.
-
- RCS is a free version control system that is available from the Free
-Software Foundation. It is perhaps the most mature of the supported
-back ends, and the VC commands are conceptually closest to RCS. Almost
-everything you can do with RCS can be done through VC.
+ 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 built on top of RCS, and extends the features of RCS, allowing
-for more sophisticated release management, and concurrent multi-user
-development. VC supports basic editing operations under CVS, but for
-some less common tasks you still need to call CVS from the command line.
-Note also that before using CVS you must set up a repository, which is a
-subject too complex to treat here.
+ 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 three that VC
-supports. VC compensates for certain features missing in SCCS
-(snapshots, for example) by implementing them itself, but some other VC
-features, such as multiple branches, are not available with SCCS. You
-should use SCCS only if for some reason you cannot use RCS.
+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. You should use
+SCCS only if for some reason you cannot use RCS, or one of the
+higher-level systems such as CVS or GNU Arch.
@node VC Concepts
@subsubsection Concepts of Version Control
@node Types of Log File
@subsubsection Types of Log File
@cindex types of log file
-@cindex log File, types of
+@cindex log File, types of
@cindex version control log
GNU projects under a revision control system generally possess
* 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
+
+@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
Compare the specified two versions of @var{file}.
@item C-x v g
-Display the result of the CVS annotate command using colors.
+Display the file with per-line version information and using colors.
@end table
@findex vc-version-other-window
@findex vc-annotate
@kindex C-x v g
- For CVS-controlled files, you can display the result of the CVS
-annotate command, using colors to enhance the visual appearance. Use
-the command @kbd{M-x vc-annotate} to do this. It creates a new buffer
+ For some backends, you can display the file @dfn{annotated} with
+per-line version information and using colors to enhance the visual
+appearance, with the the command @kbd{M-x vc-annotate}.
+It creates a new buffer
to display file's text, colored to show how old each part is. Text
colored red is new, blue means old, and intermediate colors indicate
intermediate ages. By default, the time scale is 360 days, so that
stretch factor greater than 1 means the color range spans more than a
year.
+From the annotate buffer, you can use the following keys to browse the
+annotations of past revisions, view diffs, or view log entries:
+
+@itemize @bullet
+
+@item
+Pressing @kbd{P} annotates the previous revision. It also takes a
+numeric prefix argument, so for example @kbd{C-u 10 P} would take you
+back 10 revisions.
+
+@item
+Pressing @kbd{N} annotates the next revision. It also takes a numeric
+prefix argument, so for example @kbd{C-u 10 N} would take you forward
+10 revisions.
+
+@item
+Pressing @kbd{J} annotates the revision at line (as denoted by the
+version number on the same line).
+
+@item
+Pressing @kbd{A} annotates the revision previous to line (as denoted
+by the version number on the same line). This is useful to see the
+state the file was in before the change on the current line was made.
+
+@item
+Pressing @kbd{D} shows the diff of the revision at line with its
+previous revision. This is useful to see what actually changed when
+the revision denoted on the current line was committed.
+
+@item
+Pressing @kbd{L} shows the log of the revision at line. This is
+useful to see the author's description of the changes that occurred
+when the revision denoted on the current line was committed.
+
+@item
+Pressing @kbd{W} annotates the workfile (most up to date) version. If
+you used @kbd{P} and @kbd{N} to browse to other revisions, use this
+key to return to the latest version.
+@end itemize
+
@node Secondary VC Commands
@subsection The Secondary Commands of VC
@menu
* Registering:: Putting a file under version control.
* VC Status:: Viewing the VC status of files.
-* VC Undo:: Cancelling changes before or after check-in.
-* VC Dired Mode:: Listing files managed by version control.
+* VC Undo:: Canceling changes before or after check-in.
+* VC Dired Mode:: Listing files managed by version control.
* VC Dired Commands:: Commands to use in a VC Dired buffer.
@end menu
* 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
+* Multi-User Branching:: Multiple users working at multiple branches
in parallel.
@end menu
@menu
* Change Logs and VC:: Generating a change log file from log entries.
-* Renaming and VC:: A command to rename both the source and master
+* Renaming and VC:: A command to rename both the source and master
file correctly.
* Version Headers:: Inserting version control headers into working files.
@end menu
control systems VC should handle. The default value is @code{(RCS CVS
SCCS)}, so it contains all three version systems that are currently
supported. If you want VC to ignore one or more of these systems,
-exclude its name from the list.
+exclude its name from the list. To disable VC entirely, set this
+variable to @code{nil}.
The order of systems in the list is significant: when you visit a file
registered in more than one system (@pxref{Local Version Control}),
@vindex vc-cvs-global-switches
The variable @code{vc-cvs-global-switches} should be a string
-specifyng switches to pass to CVS for all CVS operations.
+specifying switches to pass to CVS for all CVS operations.
When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
version backups, so that simple diff and revert operations are
for moving around in the file, but none for changing it; type @kbd{?}
while viewing for a list of them. They are mostly the same as normal
Emacs cursor motion commands. To exit from viewing, type @kbd{q}.
-The commands for viewing are defined by a special major mode called View
+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
the old contents of the file @var{new}.
@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
You can always specify in the file name which method should be used to
access the remote files, for example
@file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas
-@file{/sm:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}.
+@file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}.
When you don't specify a method in the file name, Emacs determines a
default method according to the following rules:
If the user name is @samp{ftp} or @samp{anonymous}, then Emacs assumes
the @command{ftp} method.
@item
-Otherwise, Emacs assumes the @command{sm} method.
+Otherwise, Emacs assumes the @command{ssh} method.
@end enumerate
@noindent
point. Partial Completion mode offers other features extending
@code{find-file}, which can be used with @code{ffap}.
@xref{Completion Options}.
+
+@ignore
+ arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250
+@end ignore