This is ../info/emacs, produced by makeinfo version 4.0 from emacs.texi.
This is the Fourteenth edition of the `GNU Emacs Manual', updated
for Emacs version 21.1.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs). The extensible self-documenting text editor.
END-INFO-DIR-ENTRY
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1985,
1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "The GNU Manifesto", "Distribution" and "GNU
GENERAL PUBLIC LICENSE", with the Front-Cover texts being "A GNU
Manual," and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled "GNU Free Documentation
License."
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
File: emacs, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save
Controlling Auto-Saving
-----------------------
Each time you visit a file, auto-saving is turned on for that file's
buffer if the variable `auto-save-default' is non-`nil' (but not in
batch mode; *note Entering Emacs::). The default for this variable is
`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 `M-x auto-save-mode'. Like other minor mode commands, `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.
Emacs does auto-saving periodically based on counting how many
characters you have typed since the last time auto-saving was done.
The variable `auto-save-interval' specifies how many characters there
are between auto-saves. By default, it is 300.
Auto-saving also takes place when you stop typing for a while. The
variable `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 `kill
%emacs', or disconnecting a phone line or network connection.
You can request an auto-save explicitly with the command `M-x
do-auto-save'.
File: emacs, Node: Recover, Prev: Auto Save Control, Up: Auto Save
Recovering Data from Auto-Saves
-------------------------------
You can use the contents of an auto-save file to recover from a loss
of data with the command `M-x recover-file <RET> FILE <RET>'. This
visits FILE and then (after your confirmation) restores the contents
from its auto-save file `#FILE#'. You can then save with `C-x C-s' to
put the recovered text into FILE itself. For example, to recover file
`foo.c' from its auto-save file `#foo.c#', do:
M-x recover-file <RET> foo.c <RET>
yes <RET>
C-x C-s
Before asking for confirmation, `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, `M-x recover-file' does not offer to read it.
If Emacs or the computer crashes, you can recover all the files you
were editing from their auto save files with the command `M-x
recover-session'. This first shows you a list of recorded interrupted
sessions. Move point to the one you choose, and type `C-c C-c'.
Then `recover-session' asks about each of the files that were being
edited during that session, asking whether to recover that file. If
you answer `y', it calls `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 `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.
Emacs records interrupted sessions for later recovery in files named
`~/.emacs.d/auto-save-list/.saves-PID-HOSTNAME'. The
`~/.emacs.d/auto-save-list/.saves-' portion of these names comes from
the value of `auto-save-list-file-prefix'. You can record sessions in
a different place by customizing that variable. If you set
`auto-save-list-file-prefix' to `nil' in your `.emacs' file, sessions
are not recorded for recovery.
File: emacs, Node: File Aliases, Next: Version Control, Prev: Auto Save, Up: Files
File Name Aliases
=================
Symbolic links and hard links both make it possible for several file
names to refer to the same file. Hard links are alternate names that
refer directly to the file; all the names are equally valid, and no one
of them is preferred. By contrast, a symbolic link is a kind of defined
alias: when `foo' is a symbolic link to `bar', you can use either name
to refer to the file, but `bar' is the real name, while `foo' is just
an alias. More complex cases occur when symbolic links point to
directories.
If you visit two names for the same file, normally Emacs makes two
different buffers, but it warns you about the situation.
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 symbolic links, or if you use a long file name on a system
that truncates long file names. You can suppress the message by
setting the variable `find-file-suppress-same-file-warnings' to a
non-`nil' value. You can disable this feature entirely by setting the
variable `find-file-existing-other-name' to `nil': then if you visit
the same file under two different names, you get a separate buffer for
each file name.
If the variable `find-file-visit-truename' is non-`nil', then the
file name recorded for a buffer is the file's "truename" (made by
replacing all symbolic links with their target names), rather than the
name you specify. Setting `find-file-visit-truename' also implies the
effect of `find-file-existing-other-name'.
File: emacs, Node: Version Control, Next: Directories, Prev: File Aliases, Up: Files
Version Control
===============
"Version control systems" are packages that can record multiple
versions of a source file, usually storing the unchanged parts of the
file just once. Version control systems also record history information
such as the creation time of each version, who created it, and a
description of what was changed in that version.
The Emacs version control interface is called VC. Its commands work
with three version control systems--RCS, CVS, and SCCS. The GNU
project recommends RCS and CVS, which are free software and available
from the Free Software Foundation. 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.
* 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.
* 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.
File: emacs, Node: Introduction to VC, Next: VC Mode Line, Up: Version Control
Introduction to Version Control
-------------------------------
VC allows you to use a version control system from within Emacs,
integrating the version control operations smoothly with editing. VC
provides a uniform interface to version control, so that regardless of
which version control system is in use, you can use it the same way.
This section provides a general overview of version control, and
describes the version control systems that VC supports. You can skip
this section if you are already familiar with the version control system
you want to use.
* Menu:
* Version Systems:: Supported version control back-end systems.
* VC Concepts:: Words and concepts related to version control.
File: emacs, Node: Version Systems, Next: VC Concepts, Up: Introduction to VC
Supported Version Control Systems
.................................
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.
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.
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.
File: emacs, Node: VC Concepts, Prev: Version Systems, Up: Introduction to VC
Concepts of Version Control
...........................
When a file is under version control, we also say that it is
"registered" in the version control system. Each registered file has a
corresponding "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 "log
entry" for each version, describing in words what was changed in that
version.
The file that is maintained under version control is sometimes called
the "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 "lock" the file before you start to edit it.)
After you are done with a set of changes, you "check the file in",
which records the changes in the master file, along with a log entry for
them.
With CVS, there are usually multiple work files corresponding to a
single master file--often each user has his own copy. It is also
possible to use RCS in this way, but this is not the usual way to use
RCS.
A version control system typically has some mechanism to coordinate
between users who want to change the same file. One method is
"locking" (analogous to the locking that Emacs uses to detect
simultaneous editing of a file, but distinct from it). The other method
is to merge your changes with other people's changes when you check them
in.
With version control locking, work files are normally read-only so
that you cannot change them. You ask the version control system to make
a work file writable for you by locking it; only one user can do this
at any given time. When you check in your changes, that unlocks the
file, making the work file read-only again. This allows other users to
lock the file to make further changes. SCCS always uses locking, and
RCS normally does.
The other alternative for RCS is to let each user modify the work
file at any time. In this mode, locking is not required, but it is
permitted; check-in is still the way to record a new version.
CVS normally allows each user to modify his own copy of the work file
at any time, but requires merging with changes from other users at
check-in time. However, CVS can also be set up to require locking.
(*note CVS Options::).
File: emacs, Node: VC Mode Line, Next: Basic VC Editing, Prev: Introduction to VC, Up: Version Control
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, `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. `-' means that the
work file is not locked (if locking is in use), or not modified (if
locking is not in use). `:' indicates that the file is locked, or that
it is modified. If the file is locked by some other user (for
instance, `jim'), that is displayed as `RCS:jim:1.3'.
File: emacs, Node: Basic VC Editing, Next: Old Versions, Prev: VC Mode Line, Up: Version Control
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.
`C-x C-q'
`C-x v v'
Perform the next logical version control operation on this file.
Strictly speaking, the command for this job is `vc-next-action',
bound to `C-x v v'. However, the normal meaning of `C-x C-q' is to
make a read-only buffer writable, or vice versa; we have extended it to
do the same job properly for files managed by version control, by
performing the appropriate version control operations. When you type
`C-x C-q' on a registered file, it acts like `C-x v v'.
The precise action of this command depends on the state of the file,
and whether the version control system uses locking or not. SCCS and
RCS normally use locking; CVS normally does not use locking.
* Menu:
* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS.
* Without Locking:: Without locking: default mode for CVS.
* Advanced C-x C-q:: Advanced features available with a prefix argument.
* Log Buffer:: Features available in log entry buffers.
File: emacs, Node: VC with Locking, Next: Without Locking, Up: Basic VC Editing
Basic Version Control with Locking
..................................
If locking is used for the file (as with SCCS, and RCS in its default
mode), `C-x C-q' can either lock a file or check it in:
* If the file is not locked, `C-x C-q' locks it, and makes it
writable so that you can change it.
* If the file is locked by you, and contains changes, `C-x C-q'
checks in the changes. In order to do this, it first reads the
log entry for the new version. *Note Log Buffer::.
* If the file is locked by you, but you have not changed it since you
locked it, `C-x C-q' releases the lock and makes the file read-only
again.
* If the file is locked by some other user, `C-x C-q' asks you
whether you want to "steal the lock" from that user. If you say
yes, the file becomes locked by you, but a message is sent to the
person who had formerly locked the file, to inform him of what has
happened.
These rules also apply when you use CVS in locking mode, except that
there is no such thing as stealing a lock.
File: emacs, Node: Without Locking, Next: Advanced C-x C-q, Prev: VC with Locking, Up: Basic VC Editing
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 `-' if the file is
unmodified; it flips to `:' as soon as you save any changes in the work
file.
Here is what `C-x C-q' does when using CVS:
* 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
_without_ trying to commit your own changes, type `C-x v m <RET>'.)
*Note Merging::.
* If there are no new changes in the master file, but you have made
modifications in your work file, `C-x C-q' checks in your changes.
In order to do this, it first reads the log entry for the new
version. *Note Log Buffer::.
* If the file is not modified, the `C-x C-q' does nothing.
These rules also apply when you use RCS in the mode that does not
require locking, except that automatic merging of changes from the
master file is not implemented. Unfortunately, this means that nothing
informs you if another user has checked in changes in the same file
since you began editing it, and when this happens, his changes will be
effectively removed when you check in your version (though they will
remain in the master file, so they will not be entirely lost). You must
therefore verify the current version is unchanged, before you check in
your changes. We hope to eliminate this risk and provide automatic
merging with RCS in a future Emacs version.
In addition, locking is possible with RCS even in this mode, although
it is not required; `C-x C-q' with an unmodified file locks the file,
just as it does with RCS in its normal (locking) mode.
File: emacs, Node: Advanced C-x C-q, Next: Log Buffer, Prev: Without Locking, Up: Basic VC Editing
Advanced Control in `C-x C-q'
.............................
When you give a prefix argument to `vc-next-action' (`C-u C-x C-q'),
it still performs the next logical version control operation, but
accepts additional arguments to specify precisely how to do the
operation.
* 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 (*note Branches::).
* 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 `C-u C-x C-q <RET>' is a convenient way to get the
latest version of a file from the repository.
* 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 (*note
Local Version Control::).
File: emacs, Node: Log Buffer, Prev: Advanced C-x C-q, Up: Basic VC Editing
Features of the Log Entry Buffer
................................
When you check in changes, `C-x C-q' first reads a log entry. It
pops up a buffer called `*VC-Log*' for you to enter the log entry.
When you are finished, type `C-c C-c' in the `*VC-Log*' buffer. That
is when check-in really happens.
To abort check-in, just *don't* type `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
`*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 `M-n',
`M-p', `M-s' and `M-r' for doing this work just like the minibuffer
history commands (except that these versions are used outside the
minibuffer).
Each time you check in a file, the log entry buffer is put into VC
Log mode, which involves running two hooks: `text-mode-hook' and
`vc-log-mode-hook'. *Note Hooks::.
File: emacs, Node: Old Versions, Next: Secondary VC Commands, Prev: Basic VC Editing, Up: Version Control
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.
`C-x v ~ VERSION <RET>'
Examine version VERSION of the visited file, in a buffer of its
own.
`C-x v ='
Compare the current buffer contents with the latest checked-in
version of the file.
`C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
Compare the specified two versions of FILE.
`C-x v g'
Display the result of the CVS annotate command using colors.
To examine an old version in its entirety, visit the file and then
type `C-x v ~ VERSION <RET>' (`vc-version-other-window'). This puts
the text of version VERSION in a file named `FILENAME.~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. *Note
Branches::.)
It is usually more convenient to compare two versions of the file,
with the command `C-x v =' (`vc-diff'). Plain `C-x v =' compares the
current buffer contents (saving them in the file if necessary) with the
last checked-in version of the file. `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
(*note Snapshots::) 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.
`C-x v =' works by running a variant of the `diff' utility designed
to work with the version control system in use. When you invoke `diff'
this way, in addition to the options specified by `diff-switches'
(*note Comparing Files::), it receives those specified by
`vc-diff-switches', plus those specified for the specific back end by
`vc-BACKEND-diff-switches'. For instance, when the version control
back end is RCS, `diff' uses the options in `vc-rcs-diff-switches'. The
`vc...diff-switches' variables are `nil' by default.
Unlike the `M-x diff' command, `C-x v =' does not try to locate the
changes in the old and new versions. This is because normally one or
both versions do not exist as files when you compare them; they exist
only in the records of the master file. *Note Comparing Files::, for
more information about `M-x diff'.
For CVS-controlled files, you can display the result of the CVS
annotate command, using colors to enhance the visual appearance. Use
the command `M-x vc-annotate' to do this. 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
everything more than one year old is shown in blue.
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 a stretch factor
for the time scale. A stretch factor of 0.1 means that the color range
from red to blue spans the past 36 days instead of 360 days. A stretch
factor greater than 1 means the color range spans more than a year.
File: emacs, Node: Secondary VC Commands, Next: Branches, Prev: Old Versions, Up: Version Control
The Secondary Commands of VC
----------------------------
This section explains the secondary commands of VC; those that you
might use once a day.
* Menu:
* Registering:: Putting a file under version control.
* VC Status:: Viewing the VC status of files.
* VC Undo:: Cancelling changes before or after check-in.
* VC Dired Mode:: Listing files managed by version control.
* VC Dired Commands:: Commands to use in a VC Dired buffer.
File: emacs, Node: Registering, Next: VC Status, Up: Secondary VC Commands
Registering a File for Version Control
......................................
You can put any file under version control by simply visiting it, and
then typing `C-x v i' (`vc-register').
`C-x v i'
Register the visited file for version control.
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 `vc-handled-backends' (*note Customizing VC::).
On the other hand, if there are no files already registered, Emacs uses
the first system from `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 `vc-handled-backends', this means that
Emacs uses RCS if there are any files under RCS control, CVS if there
are any files under CVS, SCCS if any files are under SCCS, or RCS as
the ultimate default.
If locking is in use, `C-x v i' leaves the file unlocked and
read-only. Type `C-x C-q' if you wish to start editing it. After
registering a file with CVS, you must subsequently commit the initial
version by typing `C-x C-q'.
The initial version number for a newly registered file is 1.1, by
default. You can specify a different default by setting the variable
`vc-default-init-version', or you can give `C-x v i' a numeric
argument; then it reads the initial version number for this particular
file using the minibuffer.
If `vc-initial-comment' is non-`nil', `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 (*note Log Buffer::).
File: emacs, Node: VC Status, Next: VC Undo, Prev: Registering, Up: Secondary VC Commands
VC Status Commands
..................
`C-x v l'
Display version control state and change history.
To view the detailed version control status and history of a file,
type `C-x v l' (`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.
File: emacs, Node: VC Undo, Next: VC Dired Mode, Prev: VC Status, Up: Secondary VC Commands
Undoing Version Control Actions
...............................
`C-x v u'
Revert the buffer and the file to the last checked-in version.
`C-x v c'
Remove the last-entered change from the master for the visited
file. This undoes your last check-in.
If you want to discard your current set of changes and revert to the
last version checked in, use `C-x v u' (`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. `C-x v u' requires
confirmation, unless it sees that you haven't made any changes since the
last checked-in version.
`C-x v u' is also the command to unlock a file if you lock it and
then decide not to change it.
To cancel a change that you already checked in, use `C-x v c'
(`vc-cancel-version'). This command discards all record of the most
recent checked-in version. `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 `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 `C-x v c' does not revert the buffer, it unexpands all version
control headers in the buffer instead (*note Version Headers::). This
is because the buffer no longer corresponds to any existing version.
If you check it in again, the check-in process will expand the headers
properly for the new version number.
However, it is impossible to unexpand the RCS `$Log: emacs-9,v $
However, it is impossible to unexpand the RCS `Revision 1.1.1.4 2001/10/31 18:00:31 jevans
However, it is impossible to unexpand the RCS `Import emacs 21.1 onto the vendor branch.
However, it is impossible to unexpand the RCS `' 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 `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 `yes'. Note also that this command is disabled under
CVS, because canceling versions is very dangerous and discouraged with
CVS.
File: emacs, Node: VC Dired Mode, Next: VC Dired Commands, Prev: VC Undo, Up: Secondary VC Commands
Dired under VC
..............
The VC Dired Mode described here works with all the version control
systems that VC supports. Another more powerful facility, designed
specifically for CVS, is called PCL-CVS. *Note About PCL-CVS:
(pcl-cvs)Top.
When you are working on a large program, it is often useful to find
out which files have changed within an entire directory tree, or to view
the status of all files under version control at once, and to perform
version control operations on collections of files. You can use the
command `C-x v d' (`vc-directory') to make a directory listing that
includes only files relevant for version control.
`C-x v d' creates a buffer which uses VC Dired Mode. This looks
much like an ordinary Dired buffer (*note Dired::); however, normally it
shows only the noteworthy files (those locked or not up-to-date). This
is called "terse display". If you set the variable
`vc-dired-terse-display' to `nil', then VC Dired shows all relevant
files--those managed under version control, plus all subdirectories
("full display"). The command `v t' in a VC Dired buffer toggles
between terse display and full display (*note VC Dired Commands::).
By default, VC Dired produces a recursive listing of noteworthy or
relevant files at or below the given directory. You can change this by
setting the variable `vc-dired-recurse' to `nil'; then VC Dired shows
only the files in the given directory.
The line for an individual file shows the version control state in
the place of the hard link count, owner, group, and size of the file.
If the file is unmodified, in sync with the master file, the version
control state shown is blank. Otherwise it consists of text in
parentheses. Under RCS and SCCS, the name of the user locking the file
is shown; under CVS, an abbreviated version of the `cvs status' output
is used. Here is an example using RCS:
/home/jim/project:
-rw-r--r-- (jim) Apr 2 23:39 file1
-r--r--r-- Apr 5 20:21 file2
The files `file1' and `file2' are under version control, `file1' is
locked by user jim, and `file2' is unlocked.
Here is an example using CVS:
/home/joe/develop:
-rw-r--r-- (modified) Aug 2 1997 file1.c
-rw-r--r-- Apr 4 20:09 file2.c
-rw-r--r-- (merge) Sep 13 1996 file3.c
Here `file1.c' is modified with respect to the repository, and
`file2.c' is not. `file3.c' is modified, but other changes have also
been checked in to the repository--you need to merge them with the work
file before you can check it in.
When VC Dired displays subdirectories (in the "full" display mode),
it omits some that should never contain any files under version control.
By default, this includes Version Control subdirectories such as `RCS'
and `CVS'; you can customize this by setting the variable
`vc-directory-exclusion-list'.
You can fine-tune VC Dired's format by typing `C-u C-x v d'--as in
ordinary Dired, that allows you to specify additional switches for the
`ls' command.
File: emacs, Node: VC Dired Commands, Prev: VC Dired Mode, Up: Secondary VC Commands
VC Dired Commands
.................
All the usual Dired commands work normally in VC Dired mode, except
for `v', which is redefined as the version control prefix. You can
invoke VC commands such as `vc-diff' and `vc-print-log' by typing `v
=', or `v l', and so on. Most of these commands apply to the file name
on the current line.
The command `v v' (`vc-next-action') operates on all the marked
files, so that you can lock or check in several files at once. If it
operates on more than one file, it handles each file according to its
current state; thus, it might lock one file, but check in another file.
This could be confusing; it is up to you to avoid confusing behavior
by marking a set of files that are in a similar state.
If any files call for check-in, `v v' reads a single log entry, then
uses it for all the files being checked in. This is convenient for
registering or checking in several files at once, as part of the same
change.
You can toggle between terse display (only locked files, or files not
up-to-date) and full display at any time by typing `v t'
(`vc-dired-toggle-terse-mode'). There is also a special command `* l'
(`vc-dired-mark-locked'), which marks all files currently locked (or,
with CVS, all files not up-to-date). Thus, typing `* l t k' is another
way to delete from the buffer all files except those currently locked.
File: emacs, Node: Branches, Next: Remote Repositories, Prev: Secondary VC Commands, Up: Version Control
Multiple Branches of a File
---------------------------
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
"branch". VC allows you to create branches, switch between different
branches, and merge changes from one branch to another. Please note,
however, that branches are only supported for RCS at the moment.
A file's main line of development is usually called the "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.
If you omit the final component of a version number, that is called a
"branch number". It refers to the highest existing version on that
branch--the "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.
File: emacs, Node: Switching Branches, Next: Creating Branches, Up: Branches
Switching between Branches
..........................
To switch between branches, type `C-u C-x C-q' and specify the
version number you want to select. This version is then visited
_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 <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.
File: emacs, Node: Creating Branches, Next: Merging, Prev: Switching Branches, Up: Branches
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 `C-x C-q', and make whatever changes you want. Then, when
you check in the changes, use `C-u C-x C-q'. This lets you specify the
version number for the new version. You should specify a suitable
branch number for a branch starting at the current version. For
example, if the current version is 2.5, the branch number should be
2.5.1, 2.5.2, and so on, depending on the number of existing branches at
that point.
To create a new branch at an older version (one that is no longer the
head of a branch), first select that version (*note Switching
Branches::), then lock it with `C-x C-q'. You'll be asked to confirm,
when you lock the old version, that you really mean to create a new
branch--if you say no, you'll be offered a chance to lock the latest
version instead.
Then make your changes and type `C-x C-q' again to check in a new
version. This automatically creates a new branch starting from the
selected version. You need not specially request a new branch, because
that's the only way to add a new version at a point that is not the head
of a branch.
After the branch is created, you "stay" on it. That means that
subsequent check-ins create new versions on that branch. To leave the
branch, you must explicitly select a different version with `C-u C-x
C-q'. To transfer changes from one branch to another, use the merge
command, described in the next section.
File: emacs, Node: Merging, Next: Multi-User Branching, Prev: Creating Branches, Up: Branches
Merging Branches
................
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 "merge" the changes
into a file that has already been changed otherwise. VC allows you to
do this (and other things) with the `vc-merge' command.
`C-x v m (vc-merge)'
Merge changes into the work file.
`C-x v m' (`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 <RET>, Emacs
merges any changes that were made on the same branch since you checked
the file out (we call this "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 `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 `C-u C-x C-q
<RET>'. Version 1.5 is now current. If locking is used for the file,
type `C-x C-q' to lock version 1.5 so that you can change it. Next,
type `C-x v m 1.3.1 <RET>'. This takes the entire set of changes on
branch 1.3.1 (relative to version 1.3, where the branch started, up to
the last version on the branch) and merges it into the current version
of the work file. You can now check in the changed file, thus creating
version 1.6 containing the changes from the branch.
It is possible to do further editing after merging the branch, before
the next check-in. But it is usually wiser to check in the merged
version, then lock it and make the further changes. This will keep a
better record of the history of changes.
When you merge changes into a file that has itself been modified, the
changes might overlap. We call this situation a "conflict", and
reconciling the conflicting changes is called "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 (*note Ediff: (ediff)Top.).
If you say no, the conflicting changes are both inserted into the
file, surrounded by "conflict markers". The example below shows how a
conflict region looks; the file is called `name' and the current master
file version with user B's changes in it is 1.11.
<<<<<<< name
USER A'S VERSION
=======
USER B'S VERSION
>>>>>>> 1.11
Then you can resolve the conflicts by editing the file manually. Or
you can type `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.
File: emacs, Node: Multi-User Branching, Prev: Merging, Up: Branches
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 `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 (*note Version Headers::). The
headers enable Emacs to be sure, at all times, which version number is
present in the work file.
If the files do not have version headers, you must instead tell Emacs
explicitly in each session which branch you are working on. To do this,
first find the file, then type `C-u C-x C-q' and specify the correct
branch number. This ensures that Emacs knows which branch it is using
during this particular editing session.
File: emacs, Node: Remote Repositories, Next: Snapshots, Prev: Branches, Up: Version Control
Remote Repositories
-------------------
A common way of using CVS is to set up a central CVS repository on
some Internet host, then have each developer check out a personal
working copy of the files on his local machine. Committing changes to
the repository, and picking up changes from other users into one's own
working area, then works by direct interactions with the CVS server.
One difficulty is that access to the CVS server is often slow, and
that developers might need to work off-line as well. VC is designed to
reduce the amount of network interaction necessary.
* Menu:
* Version Backups:: Keeping local copies of repository versions.
* Local Version Control:: Using another version system for local editing.
File: emacs, Node: Version Backups, Next: Local Version Control, Up: Remote Repositories
Version Backups
...............
When VC sees that the CVS repository for a file is on a remote
machine, it automatically makes local backups of unmodified versions of
the file--"automatic version backups". This means that you can compare
the file to the repository version (`C-x v ='), or revert to that
version (`C-x v u'), without any network interactions.
The local copy of the unmodified file is called a "version backup"
to indicate that it corresponds exactly to a version that is stored in
the repository. Note that version backups are not the same as ordinary
Emacs backup files (*note Backup::). But they follow a similar naming
convention.
For a file that comes from a remote CVS repository, VC makes a
version backup whenever you save the first changes to the file, and
removes it after you have committed your modified version to the
repository. You can disable the making of automatic version backups by
setting `vc-cvs-stay-local' to `nil' (*note CVS Options::).
The name of the automatic version backup for version VERSION of file
FILE is `FILE.~VERSION.~'. This is almost the same as the name used by
`C-x v ~' (*note Old Versions::), the only difference being the
additional dot (`.') after the version number. This similarity is
intentional, because both kinds of files store the same kind of
information. The file made by `C-x v ~' acts as a "manual version
backup".
All the VC commands that operate on old versions of a file can use
both kinds of version backups. For instance, `C-x v ~' uses either an
automatic or a manual version backup, if possible, to get the contents
of the version you request. Likewise, `C-x v =' and `C-x v u' use
either an automatic or a manual version backup, if one of them exists,
to get the contents of a version to compare or revert to. If you
changed a file outside of Emacs, so that no automatic version backup
was created for the previous text, you can create a manual backup of
that version using `C-x v ~', and thus obtain the benefit of the local
copy for Emacs commands.
The only difference in Emacs's handling of manual and automatic
version backups, once they exist, is that Emacs deletes automatic
version backups when you commit to the repository. By contrast, manual
version backups remain until you delete them.
File: emacs, Node: Local Version Control, Prev: Version Backups, Up: Remote Repositories
Local Version Control
.....................
When you make many changes to a file that comes from a remote
repository, it can be convenient to have version control on your local
machine as well. You can then record intermediate versions, revert to
a previous state, etc., before you actually commit your changes to the
remote server.
VC lets you do this by putting a file under a second, local version
control system, so that the file is effectively registered in two
systems at the same time. For the description here, we will assume
that the remote system is CVS, and you use RCS locally, although the
mechanism works with any combination of version control systems ("back
ends").
To make it work with other back ends, you must make sure that the
"more local" back end comes before the "more remote" back end in the
setting of `vc-handled-backends' (*note Customizing VC::). By default,
this variable is set up so that you can use remote CVS and local RCS as
described here.
To start using local RCS for a file that comes from a remote CVS
server, you must _register the file in RCS_, by typing `C-u C-x v v rcs
<RET>'. (In other words, use `vc-next-action' with a prefix argument,
and specify RCS as the back end.)
You can do this at any time; it does not matter whether you have
already modified the file with respect to the version in the CVS
repository. If possible, VC tries to make the RCS master start with
the unmodified repository version, then checks in any local changes as
a new version. This works if you have not made any changes yet, or if
the unmodified repository version exists locally as a version backup
(*note Version Backups::). If the unmodified version is not available
locally, the RCS master starts with the modified version; the only
drawback to this is that you cannot compare your changes locally to
what is stored in the repository.
The version number of the RCS master is derived from the current CVS
version, starting a branch from it. For example, if the current CVS
version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in
the RCS master will be identical to version 1.23 under CVS; your first
changes are checked in as 1.23.1.1. (If the unmodified file is not
available locally, VC will check in the modified file twice, both as
1.23 and 1.23.1.1, to make the revision numbers consistent.)
If you do not use locking under CVS (the default), locking is also
disabled for RCS, so that editing under RCS works exactly as under CVS.
When you are done with local editing, you can commit the final
version back to the CVS repository by typing `C-u C-x v v cvs <RET>'.
This initializes the log entry buffer (*note Log Buffer::) to contain
all the log entries you have recorded in the RCS master; you can edit
them as you wish, and then commit in CVS by typing `C-c C-c'. If the
commit is successful, VC removes the RCS master, so that the file is
once again registered under CVS only. (The RCS master is not actually
deleted, just renamed by appending `~' to the name, so that you can
refer to it later if you wish.)
While using local RCS, you can pick up recent changes from the CVS
repository into your local file, or commit some of your changes back to
CVS, without terminating local RCS version control. To do this, switch
to the CVS back end temporarily, with the `C-x v b' command:
`C-x v b'
Switch to another back end that the current file is registered
under (`vc-switch-backend').
`C-u C-x v b BACKEND <RET>'
Switch to BACKEND for the current file.
`C-x v b' does not change the buffer contents, or any files; it only
changes VC's perspective on how to handle the file. Any subsequent VC
commands for that file will operate on the back end that is currently
selected.
If the current file is registered in more than one back end, typing
`C-x v b' "cycles" through all of these back ends. With a prefix
argument, it asks for the back end to use in the minibuffer.
Thus, if you are using local RCS, and you want to pick up some recent
changes in the file from remote CVS, first visit the file, then type
`C-x v b' to switch to CVS, and finally use `C-x v m <RET>' to merge
the news (*note Merging::). You can then switch back to RCS by typing
`C-x v b' again, and continue to edit locally.
But if you do this, the revision numbers in the RCS master no longer
correspond to those of CVS. Technically, this is not a problem, but it
can become difficult to keep track of what is in the CVS repository and
what is not. So we suggest that you return from time to time to
CVS-only operation, using `C-u C-x v v cvs <RET>'.