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.
+project distributes CVS, GNU Arch, and RCS. 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}
* 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.
+* Old Revisions:: Examining and comparing old versions.
* Secondary VC Commands:: The commands used a little less frequently.
* Branches:: Multiple lines of development.
@ifnottex
VC allows you to use a version control system from within Emacs,
integrating the version control operations smoothly with editing.
Though VC cannot completely bridge the gaps between version-control
-systems with widely differing capabilities, it does provide
+systems with widely differing capabilities, it does provide
a uniform interface to many version control operations. Regardless of
which version control system is in use, you will be able to do basic
operations in much the same way.
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.
+* Why Version Control?:: Understanding the problems it addresses
+* Version Control Systems:: Supported version control back-end systems.
+* VCS Concepts:: Words and concepts related to version control.
+* Types of Log File:: The VCS 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:
-@dfn{reversibility}. @dfn{concurrency}, and @dfn{history}.
+@dfn{reversibility}, @dfn{concurrency}, and @dfn{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
are an important aid to memory; for a multi-person project they
become a vitally important form of communication among developers.
-@node Version Systems
+@node Version Control Systems
@subsubsection Supported Version Control Systems
@cindex back end (version control)
@cindex SCCS
SCCS was the first version-control system ever built, and was long ago
superseded by later and more advanced ones; Emacs supports it only for
-backward compatibility and historical reasons. VC compensates for
+backward compatibility and historical reasons. 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 you
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 of
-fileset changes, and keeps a history of file renaming and moving. VC
+filesets, and keeps a 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 git
git is a version-control system invented by Linus Torvalds to
support Linux kernel development. Like GNU Arch, it supports atomic
-commits of fileset changes, and keeps a history of file renaming and
+commits of filesets, and keeps a history of file renaming and
moving. One significant feature of git is that it largely abolishes
the notion of a single centralized repository; instead, each working
copy of a git project is its own repository and coordination is done
@cindex Mercurial
Mercurial is a distributed version-control systems broadly
resembling GNU Arch and git, with atomic fileset commits and
-rename/move histories. Like git it is fully decventralized.
+rename/move histories. Like git it is fully decentralized.
VC fully supports Mercurial, except for repository sync operations
which still need to be done from the command line.
-@node VC Concepts
+@node VCS Concepts
@subsubsection Concepts of Version Control
@cindex repository
@cindex work file
@cindex checking out files
- A file checked out of a version-control repository is sometimes called
-the @dfn{work file}. You edit the work file and make changes in it, as
-you would with an ordinary file. After you are done with a set of
-changes, you @dfn{check the file in}, which records the changes in the
-repository, along with a log entry for them.
+ A file checked out of a version-control repository is sometimes
+called the @dfn{work file}. You edit the work file and make changes
+in it, as you would with an ordinary file. After you are done with a
+set of changes, you @dfn{check in} or @dfn{commit} the file, which
+records the changes in the repository, along with a log entry for
+them.
+
+@cindex revision
+@cindex revision ID
+ A copy of a file stored in a repository is called a @dfn{revision}.
+The history of a file is a sequence of revisions. Each revisions is
+named by a @dfn{revision ID}. In older VCSes (such as SCCS and RCS),
+the simplest kind of revision ID consisted of a @dfn{dot-pair};
+integers (the @dfn{major} and @dfn{minor} revisions) separated by a
+dot. Newer VCSes tend to use @dfn{monotonic} revision IDs that are
+simple integers counting from 1.
To go beyond these basic concepts, you will need to understand three
ways in which version-control systems can differ from each other. They
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
+work file at any time. When you check in a file, the system will
attempt to merge your changes with any others checked into the
repository since you checked out the file.
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.
+ SCCS always uses locking. RCS is lock-based by default but can be
+told to operate in a merging style. CVS and Subversion are
+merge-based by default but can be told to operate in a locking mode.
+Most later version-control systems, such as GNU Arch, git, and
+Mercurial, have been based exclusively on merging rather than locking.
+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
between them as much as possible.
@cindex files versus changesets.
- On SCCS. RCS, CVS, and other early version-control systems, checkins
+ 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
+@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.
+with Subversion, are @dfn{changeset-based}; a checkin under these
+may include changes to several files and that change set is treated as
+a unit by the system. Any comment associated with the change belongs
+to no single 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
In fact, older versions of VC mode supported only file-based systems,
leading to some unhappy results when it was used to drive
-changeset-based ones--the Subversion support, for example, used to break
+changeset-based ones---the Subversion support, for example, used to break
up changesets into multiple per-file commits. This has been fixed, but
it has left a legacy in VC-mode's terminology. The terms ``checkin''
and ``checkout'' are associated with file-based and locking-based
``commit'' and ``update''.
@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
+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.
+ Newer version-control systems like GNU Arch, git, Mercurial, and Bzr
+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
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
+ The character between the back-end name and the revision ID
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
@node Basic VC Editing
@subsection Basic Editing under Version Control
-@node Selecting a fileset
+@menu
+* Selecting A Fileset:: Choosing a set of files to operate on
+* Doing The Right Thing:: Stepping forward in the development cycle
+* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
+* VC With A Merging VCS:: 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 Selecting A Fileset
@subsubsection Choosing the scope of your command
@cindex filesets
your fileset is the marked files only.
All files in a fileset must be under the same version-control system.
-If they are not, VC mode wil throw an error when you attempt to execute
+If they are not, VC mode will fail when you attempt to execute
a command on the fileset.
- Filesets, are, essentially, a way to pass multiple file arguments as
-a group to underlying version-control commands. For example, on
-Subversion a checkin with more than one file in its fileset will become a
-joint commit, as though you had typed @command{svn
-commit} with those file arguments at the shell command line in the
-directory of the selected buffer.
-
- If you are used to earlier versions of VC, the change in behavior you
-will notice is in VC-Dired mode. Other than @kbd{C-x v v}, most VC-mode
-commands used to operate on only one file selected by the line the
-cursor is on. The change in the behavior of @kbd{C-x v v} is more
-subtle. Formerly it operated in parallel on all marked files, but did
-not pass them to the version-control backends as a group. Now it does,
-which enables VC to drive changeset-based version-control systems.
-
-@node Doing the next logical thing
+ VC filesets are, essentially, a way to pass multiple file
+arguments as a group to underlying version-control commands. For
+example, on Subversion a checkin with more than one file in its
+fileset will become a joint commit, as though you had typed
+@command{svn commit} with those file arguments at the shell command
+line in the directory of the selected buffer.
+
+ If you are accustomed to earlier versions of VC, the change in behavior
+you will notice is in VC-Dired mode. Other than @kbd{C-x v v}, most
+VC-mode commands once operated on only one file selected by the line
+the cursor is on. The change in the behavior of @kbd{C-x v v} outside
+VC-Dired mode is more subtle. Formerly it operated in parallel on all
+marked files, but did not pass them to the version-control backends as
+a group. Now it does, which enables VC to drive changeset-based
+version-control systems.
+
+ Emacs uses the concept of named filesets elsewhere
+(@pxref{Filesets}) to allow you to view and visit files in functional
+groups. Unlike those, VC filesets are not named and don't persist
+across sessions.
+
+@node Doing The Right Thing
@subsubsection Performing the next operation in the development cycle
The principal VC command is an all-purpose command that performs
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
+@node VC With A Locking VCS
@subsubsection Basic Version Control with Locking
If locking is used for the file (as with SCCS, and RCS in its default
@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}.
+for the new revision. @xref{Log Buffer}.
@item
If the file is locked by you, but you have not changed it since you
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
+@node VC With A Merging VCS
+@subsubsection Basic Version Control with Merging
When your version-control system is merging-based rather than
locking-based---the default for CVS and Subversion, and the way GNU
-Arch always works---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.
+Arch and more modern systems always work---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 a merging-based system
-(such as CVS or Subversion in their defaiult merging mode):
+(such as CVS or Subversion in their default merging mode):
@itemize @bullet
@item
@item
If there are no new changes in the repository, 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.
+In order to do this, it first reads the log entry for the new revision.
@xref{Log Buffer}.
@item
repository 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
+effectively removed when you check in your revision (though they will
remain in the repository, so they will not be entirely lost). You must
-therefore verify that the current version is unchanged, before you
+therefore verify that the current revision is unchanged, before you
check in your changes.
In addition, locking is possible with RCS even in this mode, although
@node Advanced C-x v v
@subsubsection Advanced Control in @kbd{C-x v v}
-@cindex version number to check in/out
+@cindex revision ID 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
@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
+If the file is modified (or locked), you can specify the revision ID
+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.
+revision to select; this lets you start working from an older
+revision, or on another branch. If you do not enter any revision,
+that takes you to the highest (``head'') revision 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
+Instead of the revision ID, 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
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
+@node Old Revisions
+@subsection Examining And Comparing Old Revisions
One of the convenient features of version control is the ability
-to examine any version of a file, or compare two versions.
+to examine any revision of a file, or compare two revisions.
@table @kbd
-@item C-x v ~ @var{version} @key{RET}
-Examine version @var{version} of the visited file, in a buffer of its
+@item C-x v ~ @var{revision} @key{RET}
+Examine revision @var{revision} of the visited file, in a buffer of its
own.
@item C-x v =
-Compare the buffer contents of the current
-fileset with the focus version from which you started editing.
+Compare the buffer contents associated with the current
+fileset with the working revision(s) from which you started editing.
@item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
-Compare the specified two repository versions of the current fileset.
+Compare the specified two repository revisions of the current fileset.
@item C-x v g
-Display the file with per-line version information and using colors.
+Display the file with per-line revision information and using colors.
@end table
-@findex vc-version-other-window
+@findex vc-revision-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
+ To examine an old revision in its entirety, visit the file and then type
+@kbd{C-x v ~ @var{revision} @key{RET}} (@code{vc-revision-other-window}).
+This puts the text of revision @var{revision} in a file named
+@file{@var{filename}.~@var{revision}~}, and visits it in its own buffer
+in a separate window. (In RCS, you can also select an old revision
and create a branch from it. @xref{Branches}.)
@findex vc-diff
@kindex C-x v =
@kbd{C-x v =} compares the current buffer contents of each file in the
current fileset (saving them in the file if necessary) with the
-repository version from which you started editing each file (this is not
-necessarily the latest version of the file). The diff will be displayed
+repository revision from which you started editing each file (this is not
+necessarily the latest revision of the file). The diff will be displayed
in a special buffer in another window.
@findex vc-diff
@kindex C-u C-x v =
- You can compare two repository versions of the current fileset with
+ You can compare two repository revisions of the current fileset with
the command @kbd{C-u C-x v =} (@code{vc-diff}). @kbd{C-u C-x v =} reads
-two version numbers or tags. The diff will be displayed in a special
+two revision ID or tags. The diff will be displayed in a special
buffer in another window.
- You can specify a checked-in version by its number; an empty input
+ You can specify a checked-in revision by its ID; 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
+from all the checked-in revisions). 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.
+instead of one or both revision ID.
- Note that if your version-control system is file-oriented (SCCS, RCS,
-CVS) rather than fileset-oriented (CVS, Subversion, GNU Arch) specifying
-a version of a multiple-file fileset by number (as opposed to a snapshot
-name or RSCCS/RCS tag) is unlikely to return diffs that are connected in
-any meaningful way.
+ Note that if your version-control system is file-oriented (SCCS,
+RCS, CVS) rather than fileset-oriented (Subversion, GNU Arch, git,
+Mercurial) specifying a revision of a multiple-file fileset by
+revision ID (as opposed to a snapshot name or RSCCS/RCS tag) is
+unlikely to return diffs that are connected in any meaningful way.
If you invoke @kbd{C-u C-x v =} or @kbd{C-u C-x v =} from a buffer
that is neither visiting a version-controlled file nor a VC Dired
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.)
+revisions 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
+per-line revision 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
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
+minibuffer to read two arguments: the ID of which revision to display and
annotate (instead of the current file contents), and the time span in
days the color range should cover.
line.
@item W
-Annotate the focus version--the one you are editing. If you used
+Annotate the working revision--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.
+return to your working revision.
@end table
@node Secondary VC Commands
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
+revision by typing @kbd{C-x v v}. Until you do that, the revision ID
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-default-init-revision
+@cindex initial revision ID to register
+ The default initial revision ID for a newly registered file
+varies by what VCS you are using; normally it will be 1.1 on VCSes
+that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs.
+You can specify a different default by setting the variable
+@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a
+numeric argument; then it reads the initial revision ID 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
@table @kbd
@item C-x v l
-Display version control state and change history.
+Display revision 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,
+ To view the detailed revision 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
@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}).
+v ~} and specifying this revision's ID (@pxref{Old Revisions}).
@item d
Display the diff (@pxref{Comparing Files}) between the revision
@table @kbd
@item C-x v u
-Revert the buffer and the file to the version from which you started
+Revert the buffer and the file to the working revision from which you started
editing the file.
@item C-x v c
@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}
+working revision 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.
+haven't made any changes with respect to the master copy of the
+working revision.
@kbd{C-x v u} is also the command to unlock a file if you lock it and
then decide not to change it.
@findex vc-rollback
To cancel a change that you already checked in, use @kbd{C-x v c}
(@code{vc-rollback}). 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
+recent checked-in revision, but only if your work file corresponds to
+that revision---you cannot use @kbd{C-x v c} to cancel a revision that is
not the latest on its branch. Note that many version-control systems do
not support rollback at all; this command is something of a historical
relic.
@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
+revisions of a file. For example, you might have different revisions 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
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.
+You can create multiple branches from the trunk. How the difference
+between trunk and branch is made visible is dependent on whether the
+VCS uses dot-pair or monotonic version IDs.
+
+ In VCSes with dot-pair revision IDs, the revisions on the trunk are
+normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can
+start an independent branch. A branch starting at revision 1.2 would
+have revision ID 1.2.1.1, and consecutive revisions on this branch
+would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is
+a second branch also starting at revision 1.2, it would consist of
+revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
+
+ In VCSes with monotonic revision IDs, trunk revisions are IDed as
+1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and
+continue through 2.2, 2.3, etc. But naming conventions for branches
+and subbranches vary widely on these systems, and some (like
+Mercurial) never depart from the monotonic integer sequence at all.
+Consult the documentation of the VCS you are using.
+
+@cindex head revision
+ If you omit the final component of a dot-pair revision ID, that is called a
+@dfn{branch ID}. It refers to the highest existing revision on that
+branch---the @dfn{head revision} of that branch. The branches in the
+dot-pair example above have branch IDs 1.2.1 and 1.2.2.
@menu
* Switching Branches:: How to get to another existing branch.
@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. On a locking-based system, this
+revision ID you want to select. On a locking-based system, 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.
+ On a VCS with dot-pair IDs, you can omit the minor part, thus giving
+only the branch ID; 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
@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,
+ To create a new branch from a head revision (one that is the latest in
+the branch that contains it), first select that revision 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
+specify the revision ID for the new revision. You should specify a
+suitable branch ID for a branch starting at the current revision.
+For example, if the current revision is 2.5, the branch ID 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
+ To create a new branch at an older revision (one that is no longer the
+head of a branch), first select that revision (@pxref{Switching
Branches}). Your procedure will then differ depending on whether you
are using a locking or merging-based VCS.
- On a locking VCS, you will need to lock the old version branch with
+ On a locking VCS, you will need to lock the old revision branch 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. On
+revision, that you really mean to create a new branch---if you say no,
+you'll be offered a chance to lock the latest revision instead. On
a merging-based VCS you will skip this step.
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
+revision. This automatically creates a new branch starting from the
+selected revision. You need not specially request a new branch, because
+that's the only way to add a new revision 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
+subsequent check-ins create new revisions on that branch. To leave the
+branch, you must explicitly select a different revision 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.
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
+ You can also enter a branch ID or a pair of revision IDs 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.
+branch, or the differences between the two revisions you specified, and
+merges them into the current revision 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,
+to revision 1.5. To merge the changes from the branch to the trunk,
+first go to the head revision of the trunk, by typing @kbd{C-u C-x v v
+@key{RET}}. Revision 1.5 is now current. If locking is used for the file,
+type @kbd{C-x v v} to lock revision 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
+branch 1.3.1 (relative to revision 1.3, where the branch started, up to
+the last revision on the branch) and merges it into the current revision
of the work file. You can now check in the changed file, thus creating
-version 1.6 containing the changes from the branch.
+revision 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
+revision, then lock it and make the further changes. This will keep
a better record of the history of changes.
@cindex conflicts
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.
+master file revision with user B's changes in it is 1.11.
@c @w here is so CVS won't think this is a conflict.
@smallexample
@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.
+different branches of a file. CVS and later systems allow 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
+revisions, but all share the same common RCS records.
This technique works reliably and automatically, provided that the
source files contain RCS version headers
@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.
+The headers enable Emacs to be sure, at all times, which revision
+ID 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
+branch ID. This ensures that Emacs knows which branch it is using
during this particular editing session.
@ifnottex
a fileset. These commands are also available from the @samp{Filesets}
menu, where each existing fileset is represented by a submenu.
+ Emacs uses the concept of a fileset elsewhere @pxref{Version
+Control} to describe sets of files to be treated as a group for
+purposes of version-control operations. Those filesets are
+unnamed and do not persist across Emacs essions.
+
@ignore
arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250
@end ignore