@cindex git
@item
Git is a distributed version control system invented by Linus Torvalds to support
-Linux kernel development. It supports atomic commits of filesets and
+development of Linux (his kernel). It supports atomic commits of filesets and
file moving/renaming. 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
integer.
To go beyond these basic concepts, you will need to understand three
-ways in which version control systems can differ from each other.
+aspects in which version control systems differ.
They can be locking-based or merging-based; they can be file-based or
changeset-based; and they can be centralized or decentralized. VC
-handles all these choices, but they lead to differing behaviors which
-you will need to understand as you use it.
+handles all these modes of operation, but it cannot hide the differences.
@cindex locking versus merging
A version control system typically has some mechanism to coordinate
conflicts} happen when you check in a change to a file that conflicts
with a change checked in by someone else after your checkout. Both
kinds of conflict have to be resolved by human judgment and
-communication.
+communication. Experience has shown that merging is superior to
+locking, 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.
Distributed version control systems, such as GNU Arch, git, and
-Mercurial, are exclusively merging-based. Experience has shown that
-merging is superior to locking, both in convenience to developers and
-in minimizing the number and severity of conflicts that actually
-occur. Sometimes, however, newer version control systems may have
-locks retrofitted onto them for reasons having nothing to do with
-technology@footnote{Usually the control-freak instincts of managers.}.
+Mercurial, are exclusively merging-based.
- VC mode supports both locking and merging version control and tries
-to hide the differences between them as much as possible.
+ VC mode supports both locking and merging version control. The
+terms ``checkin'' and ``checkout'' come from locking-based version
+control systems; newer version control systems have slightly different
+operations usually called ``commit'' and ``update'', but VC hides the
+differences between them as much as possible.
@cindex files versus changesets.
On SCCS, RCS, CVS, and other early version control systems, version
Changeset-based version control is more flexible and powerful than
file-based version control; usually, when a change to multiple files
has to be reversed, it's good to be able to easily identify and remove
-all of it. But it took some years for designers to figure that out,
-and while file-based systems are passing out of use, there are lots of
-legacy repositories still to be dealt with as of this writing (2008).
-
- Prior to Emacs 23, VC supported only file-based systems, leading to
-unhappy results when it was used to drive changeset-based
-systems---the Subversion support, for example, used to break up
-changesets into multiple per-file commits. This has been fixed, but
-it has left a mark in VC's terminology. The terms ``checkin'' and
-``checkout'' are associated with file-based and locking-based systems
-and a bit archaic; nowadays those operations are usually called
-``commit'' and ``update''.
+all of it.
@cindex centralized vs. decentralized version control
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. One problem with this approach is that a single
-repository is a single point of failure---if the repository server is
-down, all work stops.
+kind of model. One of its drawbacks is that the repository is a choke
+point for reliability and efficiency.
- Newer version control systems like GNU Arch, git, Mercurial, and
-Bazaar 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.
+ GNU Arch pioneered the concept of @dfn{decentralized} version
+control, later implemented in git, Mercurial, and Bazaar. 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
portion of a program---typically one directory and its subdirectories.
A small program would use one @file{ChangeLog} file; a large program
may have a @file{ChangeLog} file in each major directory.
-@xref{Change Log}.
-
- Actually, the fact that both kinds of log exist is partly a legacy
-from file-based version control. Changelogs are a GNU convention,
-later more widely adopted, that help developers to get a
-changeset-based view of a project even when its version control system
-has that information split up in multiple file-based logs.
-
- Changeset-based version systems, on the other hand, often maintain a
-changeset-based modification log for the entire system that makes
-ChangeLogs somewhat redundant. One advantage that ChangeLogs retain
-is that it is sometimes useful to be able to view the transaction
-history of a single directory separately from those of other
-directories.
+@xref{Change Log}. Programmers have used change logs since long
+before version control systems.
+
+ Changeset-based version systems typically maintain a changeset-based
+modification log for the entire system, which makes change log files
+somewhat redundant. One advantage that they retain is that it is
+sometimes useful to be able to view the transaction history of a
+single directory separately from those of other directories.
A project maintained with version control can use just the version
control log, or it can use both kinds of logs. It can handle some
indicator to pop up a ``tool-tip'', which displays a more verbose
description of the version control status. Pressing @kbd{Mouse-1}
over the indicator pops up a menu of VC commands. This menu is
-identical to the @samp{Version Control} menu item, which can be found
-in the @samp{Tools} menu on the menu bar.
+identical to the @samp{Tools / Version Control} menu item.
@vindex auto-revert-check-vc-info
When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
@node Basic VC Editing
@subsection Basic Editing under Version Control
-@cindex filesets
+@cindex filesets, VC
Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
-group of one or more files that are treated as a unit, for the
-purposes of version control.
-
- If you are visiting a version-controlled file in the current
-buffer, the VC fileset is simply that one file. If you are visiting a
-VC directory buffer, and some files in it are marked, the VC fileset
+collection of one or more files that a VC operation acts on. When you
+type VC commands in a buffer visiting a version-controlled file, the
+VC fileset is simply that one file. When you type them in a VC
+Directory buffer, and some files in it are marked, the VC fileset
consists of the marked files (@pxref{VC Directory Mode}).
The principal VC command is an all-purpose command, @kbd{C-x v v}
(@code{vc-next-action}), that performs either locking, merging or a
-check-in on the current VC fileset, depending on the situation. You
-can call @kbd{C-x v v} from a version-controlled file, or from the VC
-Directory buffer.
+check-in (depending on the situation) on the current VC fileset. You
+can use @kbd{C-x v v} in a file-visiting buffer or in a VC Directory
+buffer.
@table @kbd
@itemx C-x v v
-Perform the next logical version control operation on the VC fileset.
+Perform the appropriate next version control operation on the VC fileset.
@end table
@findex vc-next-action
version control system; if they are not, Emacs signals an error when
you attempt to execute a command on the fileset.
- If you are accustomed to previous versions of VC, most of the
-changes to VC in Emacs 23 are found in VC directory mode (@pxref{VC
-Directory Mode}). When multiple files are marked in the VC directory
-buffer, they are treated as a VC fileset; typing @kbd{C-x v v} in the
-VC directory buffer passes them to the version control backends as a
-single unit. Other commands in VC directory mode now act on the VC
-fileset, rather than the file on the current line. These changes
-allow VC to interoperate correctly with changeset-based version
-control systems.
+ Support for VC filesets and changeset-based version control systems
+is the main improvement to VC in Emacs 23. When you mark multi-file
+VC in a VC Directory buffer, VC operations treat them as a VC fileset,
+and operate on them all at once if the version control system is
+changeset-based. @xref{VC Directory Mode}
VC filesets are distinct from the ``named filesets'' used for
viewing and visiting files in functional groups (@pxref{Filesets}).
@cindex PCL-CVS
@pindex cvs
@cindex CVS directory mode
- The VC Directory buffer described here works with all the version
-control systems that VC supports. Another more powerful facility,
-designed specifically for CVS, is called PCL-CVS. @xref{Top, , About
-PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+ The VC Directory buffer works with all the version control systems
+that VC supports. For CVS, Emacs also offers a more powerful facility
+called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
+Emacs Front-End to CVS}.
+
+@menu
+* Buffer: VC Directory Buffer. What the buffer looks like and means.
+* Commands: VC Directory Commands. Commands to use in a VC directory buffer.
+@end menu
+
+@node VC Directory Buffer
+@subsubsection The VC Directory Buffer
The VC Directory buffer contains a list of version-controlled files
in the current directory and its subdirectories. Files which are
up-to-date (have no local differences from the repository copy) are
-omitted; if all files in a directory are up-to-date, the directory is
-omitted as well. (However, the directory in which @code{vc-dir} was
-run will always be shown as @file{./}.) There is an exception to this
-rule: if VC mode detects that a file has changed to an up-to-date
-state since you last looked at it, that file and its state are shown.
+usually hidden; if all files in a subdirectory are up-to-date, the
+subdirectory is hidden as well. There is an exception to this rule:
+if VC mode detects that a file has changed to an up-to-date state
+since you last looked at it, that file and its state are shown.
If a directory uses more that one version control system, you can
select which system to use for the @code{vc-dir} command by invoking
@vindex vc-cvs-stay-local
In the above, if the repository were on a remote machine, VC only
contacts it when the variable @code{vc-stay-local} (or
-@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is
+@code{vc-cvs-stay-local}) is @code{nil} (@pxref{CVS Options}). This is
because access to the repository may be slow, or you may be working
offline and not have access to the repository at all. As a
consequence, VC would not be able to tell you that @samp{file3.c} is
@samp{CVS}; you can customize this by setting the variable
@code{vc-directory-exclusion-list}.
-@menu
-* VC Directory Commands:: Commands to use in a VC directory buffer.
-@end menu
-
@node VC Directory Commands
@subsubsection VC Directory Commands
changesets, @kbd{C-x v v} with a selected set of modified but not
committed files will commit all of them at once as a single changeset.
- When @kbd{C-x v v} (@code{vc-next-action}) operates on a set of files,
-it requires that all of those files must be either in the same state or
-in compatible states; otherwise it will throw an error (added,
-modified and removed states are considered compatible). Note that this
-differs from the behavior of older versions of VC, which did not have
-fileset operations and simply did @code{vc-next-action} on each file
+ When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
+files, all of those files must be either in the same state or in
+compatible states (added, modified and removed states are considered
+compatible). Otherwise it signals an error. This differs from the
+behavior of older versions of VC, which did not have fileset
+operations and simply did @code{vc-next-action} on each file
individually.
If any files are in a state that calls for commit, @kbd{C-x v v} reads a
@node Change Log
@section Change Logs
+@cindex change log
A change log file contains a chronological record of when and why you
have changed a program, consisting of a sequence of entries describing
individual changes. Normally it is kept in a file called
record changes for all the files in its directory and all its
subdirectories.
-@cindex change log
+@menu
+* Change Log Commands:: Commands for editing change log files.
+* Format of ChangeLog:: What the change log file looks like.
+@end menu
+
+@node Change Log Commands
+@subsection Change Log Commands
+
@kindex C-x 4 a
@findex add-change-log-entry-other-window
The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
(@pxref{Change Logs and VC}).
@end ifnottex
-@menu
-* Format of ChangeLog:: What the change log file looks like.
-@end menu
-
@node Format of ChangeLog
@subsection Format of ChangeLog
projects / emacs.git / commitdiff