X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/da1080a25c39c8f8fd1f73edcffed10d409a934f..6af24d93bec697cccba1a42275e1fdad6a407294:/doc/emacs/files.texi diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 92bd9c1bd4..04eaeac4ae 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1213,11 +1213,10 @@ description of what was changed in that version. The Emacs version control interface is called VC. Its commands work with different version control systems---currently, it supports CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU -project distributes CVS, GNU Arch, and RCS; we recommend that you use -either CVS or GNU Arch for your projects, and RCS for individual -files. We also have free software to replace SCCS, known as CSSC; if -you are using SCCS and don't want to make the incompatible change to -RCS or CVS, you can switch to CSSC. +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} @@ -1233,7 +1232,7 @@ 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 @@ -1250,7 +1249,7 @@ customizable variable @code{vc-handled-backends} to @code{nil} 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. @@ -1261,17 +1260,17 @@ this section if you are already familiar with the version control system you want to use. @menu -* Why Version Control?:: Understanding the problems it addresses -* Version Systems:: Supported version control back-end systems. -* VC Concepts:: Words and concepts related to version control. -* Types of Log File:: The per-file VC log in contrast to the ChangeLog. +* 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 @@ -1287,7 +1286,7 @@ change to it. Even for a programmer working solo change histories are an important aid to memory; for a multi-person project they become a vitally important form of communication among developers. -@node Version Systems +@node Version Control Systems @subsubsection Supported Version Control Systems @cindex back end (version control) @@ -1299,7 +1298,7 @@ git, and Mercurial. @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 @@ -1348,7 +1347,7 @@ distributed work. It differs in many ways from old well-known systems, such as CVS and RCS. It supports different transports for interoperating between users, offline operations, and it has good branching and merging features. It also supports atomic commits 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. @@ -1356,7 +1355,7 @@ 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 @@ -1368,11 +1367,11 @@ be done from the command line. @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 @@ -1387,11 +1386,22 @@ revision. @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 @@ -1417,7 +1427,7 @@ the file, making the work file read-only again. This allows other users to lock the file to make further changes. By contrast, a merging system lets each user check out and modify a -work file at any time. When you check in a a file, the system will +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. @@ -1429,14 +1439,15 @@ happen when you check in a change to a file that conflicts with a change checked in by someone else after your checkout. Both kinds of conflict have to be resolved by human judgment and communication. - SCCS always uses locking. RCS is lock-based by default but can be told -to operate in a merging style. CVS is merge-based by default but can -be told to operate in a locking mode. Most later version-control -systems, such as Subversion and GNU Arch, have been fundamentally -merging-based rather than locking-based. This is because experience -has shown that the merging-based approach is generally superior to -the locking one, both in convenience to developers and in minimizing -the number and severity of conflicts that actually occur. + 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 @@ -1448,14 +1459,14 @@ both locking and merging version control and tries to hide the differences between them as much as possible. @cindex files versus changesets. - On SCCS. RCS, CVS, and other early version-control systems, checkins + 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 @@ -1467,7 +1478,7 @@ writing in 2007. 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 @@ -1475,21 +1486,20 @@ systems and a bit archaic; nowadays those operations are usually called ``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 @@ -1562,7 +1572,7 @@ to copy it to @file{ChangeLog} 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 @@ -1584,7 +1594,16 @@ system, but is usually not excessive. @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 @@ -1600,25 +1619,31 @@ are visiting a VC Dired buffer, and some files in it are marked, 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 @@ -1647,14 +1672,7 @@ accidentally edit a file without properly checking it out first. To achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only} in your @file{~/.emacs} file. (@xref{Init Rebinding}.) -@menu -* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. -* Without Locking:: Without locking: default mode for CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. -* Log Buffer:: Features available in log entry buffers. -@end menu - -@node VC with Locking +@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 @@ -1668,7 +1686,7 @@ makes it writable so that you can change it. @item If the file is locked by you, and contains changes, @kbd{C-x v v} checks in the changes. In order to do this, it first reads the log entry -for the new version. @xref{Log Buffer}. +for the new revision. @xref{Log Buffer}. @item If the file is locked by you, but you have not changed it since you @@ -1685,18 +1703,19 @@ 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. -@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 @@ -1710,7 +1729,7 @@ to commit your own changes, type @kbd{C-x v m @key{RET}}.) @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 @@ -1722,9 +1741,9 @@ require locking, except that automatic merging of changes from the 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 @@ -1737,7 +1756,7 @@ changes in the repository automatically and notify you when they occur. @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 @@ -1745,21 +1764,21 @@ to do the operation. @itemize @bullet @item -If the file is modified (or locked), you can specify the version -number to use for the new version that you check in. This is one way +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 @@ -1843,68 +1862,68 @@ these versions are used outside the minibuffer). 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 @@ -1927,12 +1946,12 @@ the options in @code{vc-rcs-diff-switches}. The 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 @@ -1941,7 +1960,7 @@ the color is scaled over the full range of ages, such that the oldest changes are blue, and the newest changes are red. When you give a prefix argument to this command, it uses the -minibuffer to read two arguments: which version number to display and +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. @@ -1979,9 +1998,9 @@ the author's description of the changes in the revision on the current 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 @@ -2034,16 +2053,18 @@ situation. If locking is in use, @kbd{C-x v i} leaves the file unlocked and read-only. Type @kbd{C-x v v} if you wish to start editing it. After registering a file with CVS, you must subsequently commit the initial -version by typing @kbd{C-x v v}. Until you do that, the version +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 @@ -2055,12 +2076,12 @@ the initial comment works like reading a log entry (@pxref{Log Buffer}). @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 @@ -2108,7 +2129,7 @@ It also takes a numeric prefix argument as a repeat count. @item f Visit the revision indicated at the current line, like typing @kbd{C-x -v ~} and specifying this revision's number (@pxref{Old Versions}). +v ~} and specifying this revision's ID (@pxref{Old Revisions}). @item d Display the diff (@pxref{Comparing Files}) between the revision @@ -2122,7 +2143,7 @@ current line was committed. @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 @@ -2133,11 +2154,12 @@ This undoes your last check-in. @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. @@ -2146,8 +2168,8 @@ 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. @@ -2165,7 +2187,7 @@ 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 @@ -2173,18 +2195,30 @@ different branches, and merge changes from one branch to another. Please note, however, that branches are not supported for SCCS. A file's main line of development is usually called the @dfn{trunk}. -The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At -any such version, you can start an independent branch. A branch -starting at version 1.2 would have version number 1.2.1.1, and consecutive -versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, -and so on. If there is a second branch also starting at version 1.2, it -would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. - -@cindex head version - If you omit the final component of a version number, that is called a -@dfn{branch number}. It refers to the highest existing version on that -branch---the @dfn{head version} of that branch. The branches in the -example above have branch numbers 1.2.1 and 1.2.2. +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. @@ -2198,14 +2232,15 @@ example above have branch numbers 1.2.1 and 1.2.2. @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 @@ -2214,36 +2249,36 @@ other branch. @node Creating Branches @subsubsection Creating New Branches - To create a new branch from a head version (one that is the latest in -the branch that contains it), first select that version if necessary, + 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. @@ -2273,26 +2308,26 @@ since you checked the file out (we call this @dfn{merging the news}). This is the common way to pick up recent changes from the repository, regardless of whether you have already changed the file yourself. - You can also enter a branch number or a pair of version numbers in + 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 @@ -2310,7 +2345,7 @@ Ediff, Ediff, ediff, The Ediff Manual}). If you say no, the conflicting changes are both inserted into the file, surrounded by @dfn{conflict markers}. The example below shows how a conflict region looks; the file is called @samp{name} and the current -master file version with user B's changes in it is 1.11. +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 @@ -2333,12 +2368,12 @@ check in the merged version afterwards. @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 @@ -2348,13 +2383,13 @@ 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 @@ -3031,6 +3066,11 @@ files in a fileset, and @kbd{M-x filesets-close} to close them. Use 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