mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-08 15:35:02 +00:00
Code Issues Releases Activity

More updates for VC documentation.

Browse Source 
* doc/emacs/maintaining.texi (VCS Concepts): Add "working tree" terminology.
(Old Revisions): Use it.
(VCS Repositories): Add "distributed" terminology.
(Log Buffer): Remove duplicate description
about changesets.  Fix "current VC fileset" ambiguity.
(Multi-User Branching): Node deleted.
(Branches, Switching Branches): Discuss decentralized version control systems.
(VC Pull): New node.
(Merging): Document merging on decentralized systems.
(Creating Branches): Note that this is specific to CVS and related systems.
This commit is contained in:
Chong Yidong 2011-12-20 11:00:10 +08:00
parent 1154d12e5b
commit 2edef1a0a6
5 changed files with 229 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/emacs/ChangeLog
View File

@ -1,3 +1,18 @@
2011-12-20 Chong Yidong <cyd@gnu.org>
* maintaining.texi (VCS Concepts): Add "working tree" terminology.
(Old Revisions): Use it.
(VCS Repositories): Add "distributed" terminology.
(Log Buffer): Remove duplicate description
about changesets. Fix "current VC fileset" ambiguity.
(Multi-User Branching): Node deleted.
(Branches, Switching Branches): Discuss decentralized version
control systems.
(VC Pull): New node.
(Merging): Document merging on decentralized systems.
(Creating Branches): Note that this is specific to CVS and related
systems.
2011-12-19 Chong Yidong <cyd@gnu.org> 2011-12-19 Chong Yidong <cyd@gnu.org>
* maintaining.texi (VCS Merging, VCS Changesets): Index entries. * maintaining.texi (VCS Merging, VCS Changesets): Index entries.

5
doc/emacs/emacs.texi
View File

@ -776,10 +776,9 @@ VC Directory Mode
Multiple Branches of a File Multiple Branches of a File
* Switching Branches:: How to get to another existing branch. * Switching Branches:: How to get to another existing branch.
* Creating Branches:: How to start a new branch. * VC Pull:: Updating a branch from another branch.
* Merging:: Transferring changes between branches. * Merging:: Transferring changes between branches.
* Multi-User Branching:: Multiple users working at multiple branches * Creating Branches:: How to start a new branch.
in parallel.
Remote Repositories Remote Repositories

460
doc/emacs/maintaining.texi
View File

@ -164,14 +164,14 @@ meta-data, renames, copies, and deletes).
@cindex GNU Arch @cindex GNU Arch
@cindex Arch @cindex Arch
@item @item
GNU Arch is one of the earliest @dfn{distributed} version control GNU Arch is one of the earliest @dfn{decentralized} version control
systems (the other being Monotone). @xref{VCS Concepts}, for a systems (the other being Monotone). @xref{VCS Concepts}, for a
description of distributed version control systems. It is no longer description of decentralized version control systems. It is no longer
under active development, and has been deprecated in favor of Bazaar. under active development, and has been deprecated in favor of Bazaar.
@cindex git @cindex git
@item @item
Git is a distributed version control system originally invented by Git is a decentralized version control system originally invented by
Linus Torvalds to support development of Linux (his kernel). VC Linus Torvalds to support development of Linux (his kernel). VC
supports many common Git operations, but others, such as repository supports many common Git operations, but others, such as repository
syncing, must be done from the command line. syncing, must be done from the command line.
@ -179,15 +179,15 @@ syncing, must be done from the command line.
@cindex hg @cindex hg
@cindex Mercurial @cindex Mercurial
@item @item
Mercurial (hg) is a distributed version control system broadly Mercurial (hg) is a decentralized version control system broadly
resembling Git. VC supports most Mercurial commands, with the resembling Git. VC supports most Mercurial commands, with the
exception of repository sync operations. exception of repository sync operations.
@cindex bzr @cindex bzr
@cindex Bazaar @cindex Bazaar
@item @item
Bazaar (bzr) is a distributed version control system that supports Bazaar (bzr) is a decentralized version control system that supports
both repository-based and distributed versioning. VC supports most both repository-based and decentralized versioning. VC supports most
basic editing operations under Bazaar. basic editing operations under Bazaar.
@end itemize @end itemize
@ -211,6 +211,9 @@ would an ordinary file. After you are done with a set of changes, you
may @dfn{commit} (or @dfn{check in}) the changes; this records the may @dfn{commit} (or @dfn{check in}) the changes; this records the
changes in the repository, along with a descriptive log entry. changes in the repository, along with a descriptive log entry.
@cindex working tree
A directory tree of work files is called a @dfn{working tree}.
@cindex revision @cindex revision
@cindex revision ID @cindex revision ID
Each commit creates a new @dfn{revision} in the repository. The Each commit creates a new @dfn{revision} in the repository. The
@ -263,7 +266,7 @@ number and severity of conflicts that actually occur.
SCCS always uses locking. RCS is lock-based by default but can be SCCS always uses locking. RCS is lock-based by default but can be
told to operate in a merging style. CVS and Subversion are 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. merge-based by default but can be told to operate in a locking mode.
Distributed version control systems, such as GNU Arch, Git, and Decentralized version control systems, such as GNU Arch, Git, and
Mercurial, are exclusively merging-based. Mercurial, are exclusively merging-based.
VC mode supports both locking and merging version control. The VC mode supports both locking and merging version control. The
@ -295,18 +298,20 @@ all of it.
@cindex centralized version control @cindex centralized version control
@cindex decentralized version control @cindex decentralized version control
@cindex distributed version control
Early version control systems were designed around a Early version control systems were designed around a
@dfn{centralized} model in which each project has only one repository @dfn{centralized} model in which each project has only one repository
used by all developers. SCCS, RCS, CVS, and Subversion share this used by all developers. SCCS, RCS, CVS, and Subversion share this
kind of model. One of its drawbacks is that the repository is a choke kind of model. One of its drawbacks is that the repository is a choke
point for reliability and efficiency. point for reliability and efficiency.
GNU Arch pioneered the concept of @dfn{decentralized} version GNU Arch pioneered the concept of @dfn{distributed} or
control, later implemented in Git, Mercurial, and Bazaar. A project @dfn{decentralized} version control, later implemented in Git,
may have several different repositories, and these systems support a Mercurial, and Bazaar. A project may have several different
sort of super-merge between repositories that tries to reconcile their repositories, and these systems support a sort of super-merge between
change histories. In effect, there is one repository for each repositories that tries to reconcile their change histories. In
developer, and repository merges take the place of commit operations. effect, there is one repository for each developer, and repository
merges take the place of commit operations.
VC helps you manage the traffic between your personal workfiles and VC helps you manage the traffic between your personal workfiles and
a repository. Whether the repository is a single master, or one of a a repository. Whether the repository is a single master, or one of a
@ -411,14 +416,13 @@ 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 Directory buffer, and some files in it are marked, the VC fileset
consists of the marked files (@pxref{VC Directory Mode}). consists of the marked files (@pxref{VC Directory Mode}).
On Subversion and on decentralized version control systems, On modern changeset-based version control systems (@pxref{VCS
multi-file VC filesets are handled as a single group by the relevant Changesets}), VC commands handle multi-file VC filesets as a group.
version control commands. For example, committing a multi-file VC For example, committing a multi-file VC fileset generates a single
fileset generates a single revision, consisting of all the changes to revision, containing the changes to all those files. On older
those files. But on older version control systems which lack support file-based version control systems like CVS, each file in a multi-file
for group operations, such as CVS, the files in a multi-file VC VC fileset is handled individually; for example, a commit generates
fileset are passed individually to version control commands (e.g.@: a one revision for each changed file.
commit generates one revision for each changed file).
@table @kbd @table @kbd
@itemx C-x v v @itemx C-x v v
@ -428,7 +432,7 @@ VC fileset.
@findex vc-next-action @findex vc-next-action
@kindex C-x v v @kindex C-x v v
The principal VC command is an all-purpose command, @kbd{C-x v v} The principal VC command is a multi-purpose command, @kbd{C-x v v}
(@code{vc-next-action}), which performs the ``most appropriate'' (@code{vc-next-action}), which performs the ``most appropriate''
action on the current VC fileset: either registering it with a version action on the current VC fileset: either registering it with a version
control system, or committing it, or unlocking it, or merging changes control system, or committing it, or unlocking it, or merging changes
@ -599,13 +603,13 @@ variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode,
Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
(@pxref{Hooks}). (@pxref{Hooks}).
While in the @samp{*vc-log*} buffer, you can write one or more In the @samp{*vc-log*} buffer, you can write one or more @dfn{header
@dfn{header lines}, specifying additional information to be supplied lines}, specifying additional information to be supplied to the
to the version control system. Each header line must occupy a single version control system. Each header line must occupy a single line at
line at the top of the buffer; the first line that is not a header the top of the buffer; the first line that is not a header line is
line is treated as the start of the log entry. For example, the treated as the start of the log entry. For example, the following
following header line states that the present change was not written header line states that the present change was not written by you, but
by you, but by another developer: by another developer:
@smallexample @smallexample
Author: J. R. Hacker <jrh@@example.com> Author: J. R. Hacker <jrh@@example.com>
@ -617,32 +621,25 @@ Apart from the @samp{Author} header, Emacs recognizes the headers
reference to a bug fixed by the change). Not all version control reference to a bug fixed by the change). Not all version control
systems recognize all headers: Bazaar recognizes all three headers, systems recognize all headers: Bazaar recognizes all three headers,
while Git, Mercurial, and Monotone recognize only @samp{Author} and while Git, Mercurial, and Monotone recognize only @samp{Author} and
@samp{Date}. If you specify a header for a version control that does @samp{Date}. If you specify a header for a system that does not
not support it, the header is treated as part of the log entry. support it, the header is treated as part of the log entry.
@kindex C-c C-f @r{(Log Edit mode)} @kindex C-c C-f @r{(Log Edit mode)}
@findex log-edit-show-files @findex log-edit-show-files
Type @kbd{C-c C-f} (@code{log-edit-show-files}) in the
@samp{*vc-log*} buffer to view a list of files for the VC fileset that
is to be committed. If you called @kbd{C-x v v} directly from a work
file, the fileset consists of that single file. If you called
@kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory Mode}),
the fileset may consist of multiple files; in that case, @kbd{C-c C-c}
will commit those files together, as a single revision, if that is
supported by the version control system (on older version control
systems, such as CVS, each file in a multi-file VC fileset is
committed as an individual revision).
@kindex C-c C-d @r{(Log Edit mode)} @kindex C-c C-d @r{(Log Edit mode)}
@findex log-edit-show-diff @findex log-edit-show-diff
Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff} While in the @samp{*vc-log*} buffer, the ``current VC fileset'' is
of the changes between the current VC fileset and the repository considered to be the fileset that will be committed if you type
revision from which you started editing. @xref{Old Revisions}. @w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset,
type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff
of changes between the VC fileset and the version from which you
started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
(@code{log-edit-show-diff}).
@kindex C-c C-a @r{(Log Edit mode)} @kindex C-c C-a @r{(Log Edit mode)}
@findex log-edit-insert-changelog @findex log-edit-insert-changelog
If the VC fileset that is to be committed includes one or more If the VC fileset includes one or more @file{ChangeLog} files
@file{ChangeLog} files (@pxref{Change Log}), type @kbd{C-c C-a} (@pxref{Change Log}), type @kbd{C-c C-a}
(@code{log-edit-insert-changelog}) to pull the relevant entries into (@code{log-edit-insert-changelog}) to pull the relevant entries into
the @samp{*vc-log*} buffer. If the topmost item in each the @samp{*vc-log*} buffer. If the topmost item in each
@file{ChangeLog} was made under your user name on the current date, @file{ChangeLog} was made under your user name on the current date,
@ -650,7 +647,7 @@ this command searches that item for entries matching the file(s) to be
committed, and inserts them. committed, and inserts them.
@ifnottex @ifnottex
@xref{Change Logs and VC}, for the opposite way of @xref{Change Logs and VC}, for the opposite way of
working---generating ChangeLog entries from the revision control log. working---generating ChangeLog entries from the Log Edit buffer.
@end ifnottex @end ifnottex
To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that
@ -710,9 +707,8 @@ i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the
repository. Such files are labeled as @samp{added} in the VC repository. Such files are labeled as @samp{added} in the VC
Directory buffer, and show a revision ID of @samp{@@@@} in the mode Directory buffer, and show a revision ID of @samp{@@@@} in the mode
line. To make the registration take effect in the repository, you line. To make the registration take effect in the repository, you
must perform a commit (@pxref{Basic VC Editing}). Note that on must perform a commit (@pxref{Basic VC Editing}). Note that a single
changeset-based version control systems, commits can consist of both commit can include both file additions and edits to existing files.
file additions and modifications.
On a locking-based version control system (@pxref{VCS Merging}), On a locking-based version control system (@pxref{VCS Merging}),
registering a file leaves it unlocked and read-only. Type @kbd{C-x v registering a file leaves it unlocked and read-only. Type @kbd{C-x v
@ -730,14 +726,14 @@ call this command from a Dired buffer (@pxref{Dired}).
@ifnottex @ifnottex
@item M-x vc-ediff @item M-x vc-ediff
Like @kbd{C-x v =}, but using an Ediff session. @xref{Top, Ediff, Like @kbd{C-x v =}, but using Ediff. @xref{Top, Ediff, ediff, The
ediff, The Ediff Manual}. Ediff Manual}.
@end ifnottex @end ifnottex
@item C-x v D @item C-x v D
Compare all work files in the current version controlled directory Compare the entire working tree to the revision you started from
tree to the tree you started from (@code{vc-root-diff}). With a (@code{vc-root-diff}). With a prefix argument, prompt for two
prefix argument, prompt for two revisions and compare their trees. revisions and compare their trees.
@item C-x v ~ @item C-x v ~
Prompt for a revision of the current file, and visit it in a separate Prompt for a revision of the current file, and visit it in a separate
@ -788,12 +784,10 @@ Ediff session. @xref{Top, Ediff, ediff, The Ediff Manual}.
@findex vc-root-diff @findex vc-root-diff
@kindex C-x v D @kindex C-x v D
@kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
it displays a comparison between the entire current version controlled it displays the changes in the entire current working tree (i.e.@: the
tree (i.e.@: the tree controlled by the version control system working tree containing the current VC fileset). If you invoke this
associated with the current VC fileset, which may include files that command from a Dired buffer, it applies to the working tree containing
are not part of that fileset) and the tree you started with. If you the directory.
invoke this command from a Dired buffer, it applies to the entire
version controlled tree containing the directory.
@vindex vc-diff-switches @vindex vc-diff-switches
You can customize the @command{diff} options that @kbd{C-x v =} and You can customize the @command{diff} options that @kbd{C-x v =} and
@ -801,14 +795,14 @@ version controlled tree containing the directory.
from the first non-@code{nil} value amongst the variables from the first non-@code{nil} value amongst the variables
@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
@code{diff-switches} (@pxref{Comparing Files}), in that order. Here, @code{diff-switches} (@pxref{Comparing Files}), in that order. Here,
@var{backend} stands for the current version control system, @var{backend} stands for the relevant version control system,
e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the
next variable in the sequence, either of the first two may use the next variable in the sequence, either of the first two may use the
value @code{t} to mean no switches at all. Most of the value @code{t} to mean no switches at all. Most of the
@code{vc-@var{backend}-diff-switches} variables default to @code{nil}, @code{vc-@var{backend}-diff-switches} variables default to @code{nil},
but some default to @code{t}; these are for version control systems, but some default to @code{t}; these are for version control systems
such as Subversion, whose @code{diff} implementations do not accept whose @code{diff} implementations do not accept common diff options,
common diff options. such as Subversion.
@findex vc-revision-other-window @findex vc-revision-other-window
@kindex C-x v ~ @kindex C-x v ~
@ -937,7 +931,7 @@ showing only the first line of each log entry. However, you can type
@samp{*vc-change-log*} buffer to reveal the entire log entry for the @samp{*vc-change-log*} buffer to reveal the entire log entry for the
revision at point. A second @key{RET} hides it again. revision at point. A second @key{RET} hides it again.
On a distributed version control system, the @kbd{C-x v I} On a decentralized version control system, the @kbd{C-x v I}
(@code{vc-log-incoming}) command displays a log buffer showing the (@code{vc-log-incoming}) command displays a log buffer showing the
changes that will be applied, the next time you run the version changes that will be applied, the next time you run the version
control system's ``pull'' command to get new revisions from another control system's ``pull'' command to get new revisions from another
@ -1144,9 +1138,8 @@ are working offline or the network is slow.
@vindex vc-directory-exclusion-list @vindex vc-directory-exclusion-list
The VC Directory buffer omits subdirectories listed in the variable The VC Directory buffer omits subdirectories listed in the variable
@code{vc-directory-exclusion-list}. The default value of this @code{vc-directory-exclusion-list}. Its default value contains
variable contains directories that are used internally by version directories that are used internally by version control systems.
control systems.
@node VC Directory Commands @node VC Directory Commands
@subsubsection VC Directory Commands @subsubsection VC Directory Commands
@ -1268,221 +1261,174 @@ Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
bring them back at a later time). bring them back at a later time).
@node Branches @node Branches
@subsection Multiple Branches of a File @subsection Version Control Branches
@cindex branch (version control) @cindex branch (version control)
@cindex trunk (version control)
One use of version control is to maintain multiple ``current'' One use of version control is to support multiple independent lines
revisions of a file. For example, you might have different revisions of a of development, which are called @dfn{branches}. Branches are used
program in which you are gradually adding various unfinished new for maintaining separate ``stable'' and ``development'' versions of a
features. Each such independent line of development is called a program, and for developing unrelated features in isolation from one
@dfn{branch}. VC allows you to create branches, switch between another.
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}. VC's support for branch operations is currently fairly limited. For
You can create multiple branches from the trunk. How the difference decentralized version control systems, it provides commands for
between trunk and branch is made visible is dependent on whether the @dfn{updating} one branch with the contents of another, and for
VCS uses dot-pair or monotonic version IDs. @dfn{merging} the changes made to two different branches
(@pxref{Merging}). For centralized version control systems, it
In VCSes with dot-pair revision IDs, the revisions on the trunk are supports checking out different branches and committing into new or
normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can different branches.
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 @menu
* Switching Branches:: How to get to another existing branch. * Switching Branches:: How to get to another existing branch.
* Creating Branches:: How to start a new branch. * VC Pull:: Updating the contents of a branch.
* Merging:: Transferring changes between branches. * Merging:: Transferring changes between branches.
* Multi-User Branching:: Multiple users working at multiple branches * Creating Branches:: How to start a new branch.
in parallel.
@end menu @end menu
@node Switching Branches @node Switching Branches
@subsubsection Switching between Branches @subsubsection Switching between Branches
To switch between branches, type @kbd{C-u C-x v v} and specify the The various version control systems differ in how branches are
revision ID you want to select. On a locking-based system, this implemented, and these differences cannot be entirely concealed by VC.
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.
On a VCS with dot-pair IDs, you can omit the minor part, thus giving On some decentralized version control systems, including Bazaar and
only the branch ID; this takes you to the head version on the Mercurial in its normal mode of operation, each branch has its own
chosen branch. If you only type @key{RET}, Emacs goes to the highest working directory tree, so switching between branches just involves
version on the trunk. switching directories. On Git, switching between branches is done
using the @command{git branch} command, which changes the contents of
the working tree itself.
After you have switched to any branch (including the main branch), you On centralized version control systems, you can switch between
stay on it for subsequent VC commands, until you explicitly select some branches by typing @kbd{C-u C-x v v} in an up-to-date work file
other branch. (@pxref{Advanced C-x v v}), and entering the revision ID for a
revision on another branch. On CVS, for instance, revisions on the
@dfn{trunk} (the main line of development) normally have IDs of the
form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
@dots{}, and so forth. You can also specify the @dfn{branch ID},
which is a branch revision ID omitting its final component
(e.g.@: 1.2.1), to switch to the latest revision on that branch.
On a locking-based system, switching to a different branch also
unlocks (write-protects) the working tree.
Once you have switched to a branch, VC commands will apply to that
branch until you switch away; for instance, any VC filesets that you
commit will be committed to that specific branch.
@node VC Pull
@subsubsection Pulling Changes into a Branch
@table @kbd
@itemx C-x v +
On a decentralized version control system, update the current branch
by ``pulling in'' changes from another location.
On a centralized version control system, update the current VC
fileset.
@end table
@kindex C-x v +
@findex vc-pull
On a decentralized version control system, the command @kbd{C-x v +}
(@code{vc-pull}) updates the current branch and working tree. It is
typically used to update a copy of a remote branch. If you supply a
prefix argument, the command prompts for the exact version control
command to use, which lets you specify where to pull changes from.
Otherwise, it pulls from a default location determined by the version
control system.
Amongst decentralized version control systems, @kbd{C-x v +}
currently supports only Bazaar, Git, and Mercurial. On Bazaar, it
calls @command{bzr pull} for ordinary branches (to pull from a master
branch into a mirroring branch), and @command{bzr update} for a bound
branch (to pull from a central repository). On Git, it calls
@command{git pull} to fetch changes from a remote repository and merge
it into the current branch. On Mercurial, it calls @command{hg pull
-u} to fetch changesets from the default remote repository and update
the working directory.
On a centralized version control system like CVS, @kbd{C-x v +}
updates the current VC fileset from the repository.
@node Merging
@subsubsection Merging Branches
@cindex merging changes
@table @kbd
@itemx C-x v m
On a decentralized version control system, merge changes from another
branch into the current one.
On a centralized version control system, merge changes from another
branch into the current VC fileset.
@end table
While developing a branch, you may sometimes need to @dfn{merge} in
changes that have already been made in another branch. This is not a
trivial operation, as overlapping changes may have been made to the
two branches.
On a decentralized version control system, merging is done with the
command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for
the exact arguments to pass to @command{bzr merge}, offering a
sensible default if possible. On Git, this prompts for the name of a
branch to merge from, with completion (based on the branch names known
to the current repository). The output from running the merge command
is shown in a separate buffer.
On a centralized version control system like CVS, @kbd{C-x v m}
prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
Branches}); then it finds the changes from that branch, or the changes
between the two revisions you specified, and merges those changes into
the current VC fileset. If you just type @key{RET}, Emacs simply
merges any changes that were made on the same branch since you checked
the file out.
@cindex conflicts
@cindex resolving conflicts
Immediately after performing a merge, only the working tree is
modified, and you can review the changes produced by the merge with
@kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the
two branches contained overlapping changes, merging produces a
@dfn{conflict}; a warning appears in the output of the merge command,
and @dfn{conflict markers} are inserted into each affected work file,
surrounding the two sets of conflicting changes. You must then
resolve the conflict by editing the conflicted files. Once you are
done, the modified files must be committed in the usual way for the
merge to take effect (@pxref{Basic VC Editing}).
@node Creating Branches @node Creating Branches
@subsubsection Creating New Branches @subsubsection Creating New Branches
To create a new branch from a head revision (one that is the latest On centralized version control systems like CVS, Emacs supports
in the branch that contains it), first select that revision if creating new branches as part of a commit operation. When committing
necessary, lock it with @kbd{C-x v v}, and make whatever changes you a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
want. Then, when you commit the changes, use @kbd{C-u C-x v v}. This with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts
lets you specify the revision ID for the new revision. You should for a revision ID for the new revision. You should specify a suitable
specify a suitable branch ID for a branch starting at the current branch ID for a branch starting at the current revision. For example,
revision. For example, if the current revision is 2.5, the branch ID if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
should be 2.5.1, 2.5.2, and so on, depending on the number of existing and so on, depending on the number of existing branches at that point.
branches at that point.
To create a new branch at an older revision (one that is no longer the To create a new branch at an older revision (one that is no longer
head of a branch), first select that revision (@pxref{Switching the head of a branch), first select that revision (@pxref{Switching
Branches}). Your procedure will then differ depending on whether you Branches}). Your procedure will then differ depending on whether you
are using a locking or merging-based VCS. are using a locking or merging-based VCS.
On a locking VCS, you will need to lock the old revision 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 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old
revision, that you really mean to create a new branch---if you say no, 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 you'll be offered a chance to lock the latest revision instead. On a
a merging-based VCS you will skip this step. merging-based VCS you will skip this step.
Then make your changes and type @kbd{C-x v v} again to commit a new Then make your changes and type @kbd{C-x v v} again to commit a new
revision. This automatically creates a new branch starting from the revision. This creates a new branch starting from the selected
selected revision. You need not specially request a new branch, revision.
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 After the branch is created, subsequent commits create new revisions
subsequent commits create new revisions on that branch. To leave the on that branch. To leave the branch, you must explicitly select a
branch, you must explicitly select a different revision with @kbd{C-u C-x different revision with @kbd{C-u C-x v v}.
v v}. To transfer changes from one branch to another, use the merge
command, described in the next section.
@node Merging
@subsubsection Merging Branches
@cindex merging changes
When you have finished the changes on a certain branch, you will
often want to incorporate them into the file's main line of development
(the trunk). This is not a trivial operation, because development might
also have proceeded on the trunk, so that you must @dfn{merge} the
changes into a file that has already been changed otherwise. VC allows
you to do this (and other things) with the @code{vc-merge} command.
@table @kbd
@item C-x v m (vc-merge)
Merge changes into the work file.
@end table
@kindex C-x v m
@findex vc-merge
@kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
into the current version of the work file. It firsts asks you in the
minibuffer where the changes should come from. If you just type
@key{RET}, Emacs merges any changes that were made on the same branch
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 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 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 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 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 commit the changed file, thus creating
revision 1.6 containing the changes from the branch.
It is possible to do further editing after merging the branch, before
the next commit. But it is usually wiser to commit the merged
revision, then lock it and make the further changes. This will keep
a better record of the history of changes.
@cindex conflicts
@cindex resolving conflicts
When you merge changes into a file that has itself been modified, the
changes might overlap. We call this situation a @dfn{conflict}, and
reconciling the conflicting changes is called @dfn{resolving a
conflict}.
Whenever conflicts occur during merging, VC detects them, tells you
about them in the echo area, and asks whether you want help in merging.
If you say yes, it starts an Ediff session (@pxref{Top,
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 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
@group
@w{<}<<<<<< name
@var{User A's version}
=======
@var{User B's version}
@w{>}>>>>>> 1.11
@end group
@end smallexample
@findex vc-resolve-conflicts
Then you can resolve the conflicts by editing the file manually. Or
you can type @code{M-x vc-resolve-conflicts} after visiting the file.
This starts an Ediff session, as described above. Don't forget to
commit the merged version afterwards.
@findex vc-find-conflicted-file
If there is more than one conflicted file in a merge, type @kbd{M-x
vc-find-conflicted-file} after resolving the conflicts in each file.
This command visits the next conflicted file, and moves point to the
first conflict marker in that file.
@node Multi-User Branching
@subsubsection Multi-User Branching
It is often useful for multiple developers to work simultaneously on
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
@iftex
(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Version Headers}).
@end ifnottex
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 ID. This ensures that Emacs knows which branch it is using
during this particular editing session.
@ifnottex @ifnottex
@include vc1-xtra.texi @include vc1-xtra.texi

9
doc/emacs/vc1-xtra.texi
View File

@ -495,14 +495,7 @@ a mechanism, except GNU Arch.
VC does not normally use the information contained in these headers. VC does not normally use the information contained in these headers.
The exception is RCS---with RCS, version headers are sometimes more The exception is RCS---with RCS, version headers are sometimes more
reliable than the master file to determine which version of the file reliable than the master file to determine which version of the file
you are editing. Note that in a multi-branch environment, version you are editing.
headers are necessary to make VC behave correctly
@iftex
(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}).
@end iftex
@ifnottex
(@pxref{Multi-User Branching}).
@end ifnottex
Searching for RCS version headers is controlled by the variable Searching for RCS version headers is controlled by the variable
@code{vc-consult-headers}. If it is non-@code{nil} (the default), @code{vc-consult-headers}. If it is non-@code{nil} (the default),

14
etc/NEWS
View File

@ -833,19 +833,21 @@ controlling the degree of parallelism.
** VC and related modes ** VC and related modes
+++
*** Support for pulling on distributed version control systems. *** Support for pulling on distributed version control systems.
The vc-pull command runs a "pull" operation, if it is supported. `C-x v +' (`vc-pull') runs a "pull" operation, if it is supported, to
This updates the current branch from upstream. A prefix argument update the current branch and working tree. A prefix argument means
means to prompt the user for specifics, e.g. a pull location. to prompt the user for specifics, e.g. a pull location.
**** `vc-update' is now an alias for `vc-pull'. **** `vc-update' is now an alias for `vc-pull'.
**** Currently supported by Bzr, Git, and Mercurial. **** Currently supported by Bzr, Git, and Mercurial.
+++
*** Support for merging on distributed version control systems. *** Support for merging on distributed version control systems.
The vc-merge command now runs a "merge" operation, if it is supported. The vc-merge command now runs a "merge" operation, if it is supported,
This merges another branch into the current one. This command prompts to merge changes from another branch into the current one. It prompts
the user for specifics, e.g. a merge source. for specifics, e.g. a merge source.
**** Currently supported for Bzr, Git, and Mercurial. **** Currently supported for Bzr, Git, and Mercurial.