Article-CVS-branching/eclipse_branch.html - www.eclipse.org/articles - Git at Google

 <html>

 <head>
 <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
 <title>Branching with Eclipse and CVS</title>
 <link rel="stylesheet" href="../default_style.css">
 </head>

 <body LINK="#0000ff" VLINK="#800080">
 <div align="right"> &copy; Copyright IBM Corp. 2003
   <table border=0 cellspacing=0 cellpadding=2 width="100%">
     <tr>
       <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">&nbsp;Eclipse
         Corner Article</font></font></b></td>
     </tr>
   </table>
 </div>
 <div align="left">
   <h1><img src="images/Idea.jpg" height=86 width=120 align=CENTER></h1>
 </div>
 <p>&nbsp;</p>

 <h1 ALIGN="CENTER">Branching with Eclipse and CVS</h1>

 <blockquote>
 <b>Summary</b>

 <br>
   This article presents a brief branch and merge scenario designed
   to quickly illustrate some branch and merge features of Eclipse's
   CVS integration.  I assume the reader already appreciates the value
   of branching and merging in a source control environment.  Little
   is said to justify it here.  Rather, a step-by-step scenario
   illustrates the common branch and merge operations using
   Eclipse-based IDEs with CVS as the source control mechanism.
   <p><b> By Paul Glezen, IBM</b> <br>
     <font size="-1">July 3, 2003</font> </p>
 </blockquote>

 <hr width="100%">

 <h2>Introduction</h2>

 In any source control management (SCM) environment, branching is a powerful mechanism
 for controlled isolation. Despite being a simple concept, it is sometimes avoided
 because of its implementation complexities. This brief article demonstrates how
 to perform branching with Eclipse's CVS plug-in. The intended audience is software
 development professionals with an appreciation for the roles of branch and merge
 techniques in SCM.
 <p>
 The IBM&reg; redbook, <i>WebSphere&reg; Studio Application Developer Programming
 Guide</i>, contains a section entitled <i>Streams in CVS</i>.  It
 addresses branching and merging using CVS with Eclipse.  But many of
 the menu choices have changed since its publication.  The Eclipse online
 documentation is accurate, but does not provide an end-to-end scenario.
 The intent of this article is to fill this gap.  The version of Eclipse
 used for this article is 2.1.
 <p>
 The scenario is that of two programmers, Paul and Wing, working on
 separate branches of the same project.  Paul will branch off main and
 modify some files while Wing continues to work on the main branch,
 also modifying files.  Paul will then merge his branch back to the
 main branch.  In doing so, Paul will address the resulting merge conflicts.
 <p><center>
 <img src="images/intro.jpg" alt="Elementary Branch Concept"/>
 </center><p>

 <h2>Setup</h2>

 The sample will use a few text files inside a simple project.  In order
 to carry out the sample, you should already have a working connection to
 a CVS repository in your Eclipse workspace.
 <p><ol type="a">
 <li>Create a new simple project called <b>brtest</b>.<p>
 <li>Add a new file called <code>f1.txt</code>.  Add the following contents.
 <p><table border="1">
 <tr><td>
 <pre>This file will only be edited
 by Paul

 This line will be changed later.

 The rest of this file will
 remain the same.
 </pre></table><p>

 <li>Add a file called <code>f2.txt</code> with the following contents.
 <p><table border="1">
 <tr><td>
 <pre>This file will only be edited
 by Wing.

 This line will be changed later.

 The rest of this file will
 remain the same.</pre>
 </table><p>

 <li>Add a file called <code>f3trivial.txt</code> with the following
 contents.
 <p><table border="1">
 <tr><td>
 <pre>This file will be edited by
 Paul and Wing.

 This line will be changed
 by Paul only.

 This line will be left alone.

 This line will be changed
 by Wing only.

 The rest of this file will
 remain the same.</pre>
 </table><p>

 <li>Add a file called <code>f4conflict.txt</code> with the
 following contents.
 <p><table border="1">
 <tr><td>
 <pre>This file will be edited by
 Paul and Wing.

 This line will be changed by
 by both Paul and Wing.

 The rest of this file will
 remain the same.</pre>
 </table><p>
 After adding the above files, your workspace should look something
 like the screen shot below.
 <p>
 <img src="images/filelist.jpg" alt="Starting list of files in resource view"/>
 <p>

 <li>Add the project to CVS.  Right-click on the project folder
    and select <b>Team --&gt; Share Project</b>.  Select CVS as
    the project type and click <b>Next</b>.  Choose a suitable
    respository and click <b>Next</b>.  This creates an empty CVS
    project called <b>brtest</b>.  We still need to add the
    files to source control and commit them.<p>

 <li>In the <b>Synchronize - Outgoing Mode</b> view, right-click
    the <i>brtest</i> folder and select <b>Add to Version Control</b>.
    Once again, right-click on the <i>brtest</i> folder and select
    <b>Commit ...</b> .  Provide an initial comment such as
    "Initial Version."<p>
 </ol>

 This sets up the environment for Paul.  Wing will work
 in her own workspace by retrieving the files from source control.
 For steps on setting up a new project from source control, see the
 following section in the Eclipse documentation: <b>Workbench User's
 Guide --&gt; Tasks --&gt; Working in the team environment --&gt;
 Checking out a project from a CVS repository</b>.

 <h2>Branch Method</h2>

 When branching off a development stream, it is often advisable to
 rebase before merging the branch back to the main branch.  To
 <b>rebase</b> means to merge the contents of the main branch to
 the subbranch.  If any conflicts are to be resolved, they are done
 on the subbranch rather than the main branch.  If the merge goes
 well, the subbranch is merged to the main branch.  After having
 previously resolved all merge conflicts, this last merge would be
 a trivial one.  The advantage of taking the extra rebase step is
 that it avoids having conflicts on the main branch.
 <p>
 For this simple example, Paul will simply merge his changes directly
 into the main branch.  From the prospective of implementation details,
 the only difference is the merge target.  Since this article is
 principally concerned with implementation details of the Eclipse
 branch support using CVS, the simplest branch method is sufficient.

 <h2>Creating the Branch</h2>

 At this point, Paul and Wing have the same version of all files.  It
 is now time for Paul to create an independent branch on which to work.
 <p><ol>
 <li>Right-click on the <i>brtest</i> project and select <b>Team --&gt;
    Branch ...</b>.  A <i>Create Branch</i> dialog box is displayed.
    Enter a branch name like "p1test."  Leave the check box checked for
    <b>Start working in the branch</b>.  Notice that a version name is
    automatically filled in for you called "Root_p1test."  You may
    choose a different name (so long as it doesn't conflict with an
    existing CVS tag).  This will mark where the branch was created.
    It will be used later by the merge editor to determine what has
    changed since branch creation.  Click <b>OK</b>.
    <p> <img src="images/makebranch.jpg"
             alt="Dialog for creating a new branch"/>
    <p>
    You should be able to see the result of your branch in two ways.  By
    right-clicking the project and selecting <b>Properties</b> and then
    <b>CVS</b>, you should see the <i>p1test</i> in the tag field.  If
    you have the CVS label decorations enabled, you'll see the branch
    tag in the navigator view (see below).
    <p><img src="images/branchlist.jpg"
            alt="CVS labels indicating new branch"/>
    <p><table><tr><td>
 	   <img src="images/tip.gif" width="62" height="13">
 		<td>To enable CVS label decorations, go to <b>Window --&gt;
 		Preferences</b> and navigate to <b>Workbench --&gt; Label
 		Decorations</b>.  Check the CVS box.
 	</table><p>

 	<li>Paul will modify the first file using the <i>p1test</i> branch.
 	Open the editor for <code>f1.txt</code>.  Change line 4 from "This line
 	will be changed later" to "This line has been changed."  Save the
 	change.<p>

 	<li>Open the editor for <code>f3trivial.txt</code>.  Change line 4 and
 	5 from "This line will be changed by Paul only" to "This line has
 	been changed by Paul."  Save the change.<p>
    <li>Open the editor for <code>f4conflict.txt</code>.  Change lines 4 and
 	5 from "This line will be changed by both Paul and Wing" to "This
 	line has been changed by Paul."  Save the change.<p>

 	<li>Right-click on the <i>brtest</i> project and select <b>Team
 	--&gt; Synchronize with Repository</b>.  In the <b>Outgoing Mode</b>
 	view, right-click the <i>brtest</i> project folder and select
 	<b>commit</b>.  Enter a comment such as "Changes made by Paul."  Note
 	that for files that have changed, the revision numbers are four digits.
 	This is a CVS convention for branched revisions.
 	<p><img src="images/p1commit.jpg"
 	        alt="Paul's CVS label decorations after commit"/>
 	<p>

 	<li>Now it is Wing's turn.  She will make her changes on the main
 	branch.  Since she already had the main branch loaded into her
 	workspace, she doesn't need to perform a branch change.  As Wing,
 	begin editing <code>f2.txt</code>.  Change "This line will be changed
 	later" to "This line has been changed."  Save the change.<p>

 	<li>Edit <code>f3trivial.txt</code> in Wing's workspace.  Change lines
 	9 and 10 from "This line will be changed by Wing only" to "This
 	line has been changed by Wing."  Save the change.<p>

 	<li>Edit <code>f4conflict.txt</code> in Wing's workspace.  Change lines
 	4 and 5 from "This line will be changed by Paul and Wing" to "This
 	line was changed by Wing."  Save the change.<p>

 	<li>Commit Wing's changes.  Notice her revisions numbers are all two
 	digits.  That's because her new revisions occur on the main branch.<p>

 </ol>
 <br>

 <h2>The Merge</h2>

 Now it is time for Paul to merge his changes into the main branch
 where Wing's work resides.

 <p><ol start="10"/>
 <li>The first step of the merge is to point
 	the workspace to the target branch.  In our case, the target
 	of the merge is the main branch.  To switch the project contents
 	to that of the main branch, right-click on the <i>brtest</i>
 	project in the Navigator view and select <b>Replace with --&gt;
 	Branch or Version ...</b>.  You should see a branch selection
 	similar to the one below.
 	<p><img src="images/branchswitch.jpg"
 	        alt="Dialog for selecting new branch or version"/>
 	<p>

 <li>The <i>p1test</i> branch is the one Paul was working on. To
 	switch back to the main branch, select <b>HEAD</b>.  This is
 	the CVS name for the main branch.  Make sure <b>Recurse into
 	sub-folders</b> is checked so that all the files in the project
 	are replaced with the main branch contents.  Then click <b>OK</b>.
 	<p>
 	The resource view should look like the one below.  Notice the
 	version numbers correspond to what Wing committed.  All the
 	version numbers are two digits.  The branch name is gone which
 	implies the <i>HEAD</i> branch (or main).
 	<p><img src="images/afterswitch.jpg"
 	        alt="Resource view after switching back to main branch"/>
 	<p>

 	<li>Right-click on the <i>brtest</i> project and select <b>Team --&gt;
 	Merge ...</b>.  This displays a panel allowing you to choose a "start
 	point."  For this example, the only start point available is
 	<b>Root_p1test</b>, the one
 	Paul made by creating the branch.  Select it and click <b>Next</b>.
 	<p><img src="images/mergestartpoint.jpg"
 	        alt="Dialog for choosing a merge start point"/>
 	<p>

 	<li>Next we specify from which branch to pull the changes.  Expand
 	the <b>Branches</b> node and select <b>p1test</b>.  Click
 	<b>Finish</b>.<p>
 	<p><img src="images/mergewhat.jpg"
 	        alt="Dialog for selecting choosing a branch to merge"/>
 	<p>

 	<li>This is where the fun begins.  You will be presented with the
 	Merge Editor's Structure Compare view with the following merge
 	results.
 	<p><img src="images/conflict1.jpg"
 	        alt="Merge tasks."/>
 	<p>
 	<code>f1.txt</code> was not changed by Wing, so it will come in without
 	a problem.  But <code>f3trivial.txt</code> and <code>f4conflict.txt</code>
 	were each modified by both Paul and Wing.  These will require special
 	attention during the merge.<p>

 	<li>Right-click on the <i>brtest</i> folder and select <b>Update
 	from Repository</b>.  This action only operates on non-conflicting
 	resources (those with no red marks) in the <i>Structure Compare</i>
 	view.  In our example, it pulls in the changes to <code>f1.txt</code>.
 	This should leave your <i>Structure Compare</i> view with only two
 	conflicts.<p>

 	<li>Right-click <code>f3trivial.txt</code> in the Structure Compare view
 	and select <b>Merge changes into Local Copy</b>.  Since
 	<code>f3trivial.txt</code> was a trivial merge, the merge editor
 	automatically copies the changes from the <i>p1test</i> branch into
 	our local copy of the main branch.  Inspection of <code>f3trivial.txt</code>
 	will reveal the changes made by both Paul and Wing.
 	<p><table><tr>
 	<td><b>Note</b>
 	<td>We haven't merged into main yet.  That doesn't happen until we
 	commit.  For now we've just merged into our local copy; hence the
 	name of the menu option.
 	</table><p>
 	You should see an additional file, <code>.#f3trivial.txt</code>, in the
 	resource view that isn't under source control.  It contains a copy
 	of the pre-merge contents for restoration purposes.<p>

 	<li>Double-click <code>f4conflict.txt</code> to open the <i>Structure
 	Compare</i> view of the merge tool.  The left side of the <i>Text
 	Compare</i> panel is the local copy of the main branch contents.
 	The left side is the <i>brtest</i> branch contents.  Since this is
 	not a trivial merge, the color red is used to delineate the scope
 	of each merge conflict.  Blue would be used to denote trivial
 	merges.
 	<p><img src="images/conflict7.jpg"
 	        alt="Resolving conflicts with merge editor"/>
 	<p>
 	We can't resolve this conflict by simply using one side or the
 	other.  For this case, we edit the text in the left side to say
 	"This line has been changed by Paul and Wing."  Right-click in
 	this same text window and select <b>Save</b>.<p>

 	<li>Since we have finished manually merging <code>f4conflict.txt</code>,
 	we no longer need to retain it in the <i>Structure Compare</i> view.
 	Right-click <code>f4conflict.txt</code> in the <i>Structure Compare</i>
 	view and select <b>Remove From View</b>.  This only removes it from
 	the view, not from the project.<p>

 	<li>At this point, the merged copy only exists in our workspace.
 	We still need to save it to the CVS respository.  Select the
 	<i>brtets</i> project in the <i>Navigator</i> view and select
 	<b>Team --&gt; Synchronize with Repository</b>.  These changes
 	should not present any conflicts.  Right-click on the <i>brtest</i>
 	folder in the <i>Synchronize</i> view and select <b>Commit</b>.
 	A suitable comment would be "Merged prtest branch to main."<p>


 <li>A successful merge is often an occasion for a release. In CVS, this amounts
   to tagging all the files with a given tag. In this case, we'll tag it with "p12merge."
   Right-click the <i>brtest</i> project in the <i>Navigator</i> view and select
   <b>Team --&gt; Tag as version ...</b> from its context menu. Enter the name
   "p12merge" for the tag name. Click <b>Finish</b>.
   <p> </ol> <br>
   <h2>Summary</h2>
   In this brief tutorial we illustrated the implementation steps for a simple
   branch and merge scenario. Several files were used to demonstrate different
   types of conflicts that arise during merge activity. In cases where two developers
   edited the same file, we saw the action taken by the <b>Merge changes with Local
   Copy</b> on a file with only trivial conflicts. We saw how to use the merge
   editor to manually resolve non-trivial conflicts. The appendix contains a re-run
   of steps 17 and 18 that use <b>Merge changes with Local Copy</b> on <code>f4conflict.txt</code>.
   <p> After the merge task was complete, we tagged the results to create a release.
     Others can then refer to this release using the name "p12merge." A summary
     of our actions for a single file is obtained by right-clicking on the file
     in the <i>Navigator</i> view and selecting <b>Team --&gt; Show in resource
     history</b>. The resource history for <code>f4conflict.txt</code> is show
     below.
   <p><img src="images/f4history.jpg"
         alt="f4conflict.txt revision history"/>
   <p> We can barely see the <i>Root_p1test</i> tag assigned to revision 1.1, the
     initial version. We see that Paul made changes that were committed to a branch
     while Wing made changes that were committed to main. Finally, the merge resulted
     in revision 1.3, which was tagged for posterity with the label "p12merge."
   <p> For a software developer, the task of merging ranks among status-reports
     and schedule-estimation in terms of loathing. It's not difficult to image
     how the seductively simple "trivial merge" can lead to subtle non-trivial
     problems in code. Eclipse's CVS integration strives to ease this burden by
     putting a friendlier face on branch and merge support.
   <h2>Appendix</h2>
   In steps 17 and 18, we chose to employ the manual merge facilities for the non-trivial
   merge. This appendix describes an alternative to these steps using the automated
   <b>Merge Changes into Local Copy</b> option. Upon encountering a non-trivial
   conflict, this option will insert merge markers in the file. The resource view
   will signify the merge conflict with a special icon marker.
   <p> This alternative works great for simple text files. For source code it can
     result in unexpected compilation behavior if incremental builds are enabled.
     For this reason, the manual merge step was chosen for steps 17 and 18 above.
     These steps are re-worked here using the automated approach for readers that
     prefer this method.
   <p>
   <table>
     <tr>
       <td><img src="images/tip.gif"/>
       <td>It is recommended that <i>incremental compilation</i> be disabled when
         using this method on source code files. This is done from the <b>Windows
         --&gt; Preferences</b> dialog by selecting <b>Workbench</b> on the left
         side and unchecking <b>Perform build automatically on resource modification</b>.
   </table>
   <p>
   <ol start="17">
     <li>Right-click <code>f4conflict.txt</code> and select <b>Merge changes into
       Local Copy</b>. Since this is not a trivial merge, the result will contain
       merge markers that indictate where the conflict occurred. Markers in the
       resource view indicate which files were marged non-trivially.
       <p><img src="images/conflict6.jpg"
 	        alt="A merge conflict marker"/>
       <p> In the figure above, the non-trivial merge marker appears on <code>f4conflict.txt</code>.
       <p> Note the presence of two additional files not under source control.
         <code>.#f3trivial.txt</code> and <code>.#f4conflict.txt</code> files contain
         copies of the pre-merge contents for restoration purposes.
       <p>
     <li>We now want to resolve the merge conflict for <code>f4conflict.txt</code>
       indicated in the resource view above. Open the <code>f4conflict.txt</code>
       in an editor.
       <p><img src="images/conflict5.jpg"
 	        alt="Merge markers in a file."/>
       <p> Note the manner in which the merge editor calls attention to different
         versions of the same line. It is up to us to resolve the conflict and
         remove the markers. In this case, we replace the lines between "<code>&gt;&gt;&gt;
         f4conflict.txt</code>" and "<code>&lt;&lt;&lt; 1.1.4.1</code>", inclusive,
         to contain "This line has been changed by Paul and Wing." Then save the
         result.
       <p> Notice that saving the result will change the merge conflict marker.
         The assumption is that the save action resolves the conflict.
       <p>
   </ol>
   <br>
   <h2>References</h2>
   Listed below are some references to which one can refer in addition to the Eclipse
   documentation.
   <p>
   <ul>
     <li><i>WebSphere Studio Application Developer Programming Guide</i>, <a href="http://www.redbooks.ibm.com/">http://www.redbooks.ibm.com</a>,
       SG24-6585-00. This reference applies to version 4 of WSAD. The underlying
       Eclipse version is 1.0. Its section on branching and merging provided the
       motivation for writing this article.
       <p>
     <li><i>WebSphere Studio Application Developer Version 5 Programming Guide</i>,
       <a href="http://www.redbooks.ibm.com/"> http://www.redbooks.ibm.com</a>,
       SG24-6957-00. This reference was still in draft stage at the time of this
       writing. It contains a section on branch and merging. The underlying Eclipse
       version is 2.0.
       <p>
     <li><i>Version Management with CVS</i>, Per Cederqvist et al. <a href="http://www.cvshome.org/docs/manual">
       http://www.cvshome.org/docs/manual</a>. This manual is the standard CVS
       reference.
   </ul>
   <p>
   <hr>
   <p><small> <font size="-2">IBM and WebSphere are registered trademarks of IBM
     Corp. in the United States, other countries, or both. </font></small>
   <p>
 </body>
 </html>
	<html>

	<head>
	<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
	<title>Branching with Eclipse and CVS</title>
	<link rel="stylesheet" href="../default_style.css">
	</head>

	<body LINK="#0000ff" VLINK="#800080">
	<div align="right"> © Copyright IBM Corp. 2003
	<table border=0 cellspacing=0 cellpadding=2 width="100%">
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF"> Eclipse
	Corner Article</font></font></b></td>
	</tr>
	</table>
	</div>
	<div align="left">
	<h1><img src="images/Idea.jpg" height=86 width=120 align=CENTER></h1>
	</div>
	<p> </p>

	<h1 ALIGN="CENTER">Branching with Eclipse and CVS</h1>

	<blockquote>
	<b>Summary</b>

	<br>
	This article presents a brief branch and merge scenario designed
	to quickly illustrate some branch and merge features of Eclipse's
	CVS integration. I assume the reader already appreciates the value
	of branching and merging in a source control environment. Little
	is said to justify it here. Rather, a step-by-step scenario
	illustrates the common branch and merge operations using
	Eclipse-based IDEs with CVS as the source control mechanism.
	<p><b> By Paul Glezen, IBM</b> <br>
	<font size="-1">July 3, 2003</font> </p>
	</blockquote>

	<hr width="100%">

	<h2>Introduction</h2>

	In any source control management (SCM) environment, branching is a powerful mechanism
	for controlled isolation. Despite being a simple concept, it is sometimes avoided
	because of its implementation complexities. This brief article demonstrates how
	to perform branching with Eclipse's CVS plug-in. The intended audience is software
	development professionals with an appreciation for the roles of branch and merge
	techniques in SCM.
	<p>
	The IBM® redbook, <i>WebSphere® Studio Application Developer Programming
	Guide</i>, contains a section entitled <i>Streams in CVS</i>. It
	addresses branching and merging using CVS with Eclipse. But many of
	the menu choices have changed since its publication. The Eclipse online
	documentation is accurate, but does not provide an end-to-end scenario.
	The intent of this article is to fill this gap. The version of Eclipse
	used for this article is 2.1.
	<p>
	The scenario is that of two programmers, Paul and Wing, working on
	separate branches of the same project. Paul will branch off main and
	modify some files while Wing continues to work on the main branch,
	also modifying files. Paul will then merge his branch back to the
	main branch. In doing so, Paul will address the resulting merge conflicts.
	<p><center>
	<img src="images/intro.jpg" alt="Elementary Branch Concept"/>
	</center><p>

	<h2>Setup</h2>

	The sample will use a few text files inside a simple project. In order
	to carry out the sample, you should already have a working connection to
	a CVS repository in your Eclipse workspace.
	<p><ol type="a">
	<li>Create a new simple project called <b>brtest</b>.<p>
	<li>Add a new file called <code>f1.txt</code>. Add the following contents.
	<p><table border="1">
	<tr><td>
	<pre>This file will only be edited
	by Paul

	This line will be changed later.

	The rest of this file will
	remain the same.
	</pre></table><p>

	<li>Add a file called <code>f2.txt</code> with the following contents.
	<p><table border="1">
	<tr><td>
	<pre>This file will only be edited
	by Wing.

	This line will be changed later.

	The rest of this file will
	remain the same.</pre>
	</table><p>

	<li>Add a file called <code>f3trivial.txt</code> with the following
	contents.
	<p><table border="1">
	<tr><td>
	<pre>This file will be edited by
	Paul and Wing.

	This line will be changed
	by Paul only.

	This line will be left alone.

	This line will be changed
	by Wing only.

	The rest of this file will
	remain the same.</pre>
	</table><p>

	<li>Add a file called <code>f4conflict.txt</code> with the
	following contents.
	<p><table border="1">
	<tr><td>
	<pre>This file will be edited by
	Paul and Wing.

	This line will be changed by
	by both Paul and Wing.

	The rest of this file will
	remain the same.</pre>
	</table><p>
	After adding the above files, your workspace should look something
	like the screen shot below.
	<p>
	<img src="images/filelist.jpg" alt="Starting list of files in resource view"/>
	<p>

	<li>Add the project to CVS. Right-click on the project folder
	and select <b>Team --> Share Project</b>. Select CVS as
	the project type and click <b>Next</b>. Choose a suitable
	respository and click <b>Next</b>. This creates an empty CVS
	project called <b>brtest</b>. We still need to add the
	files to source control and commit them.<p>

	<li>In the <b>Synchronize - Outgoing Mode</b> view, right-click
	the <i>brtest</i> folder and select <b>Add to Version Control</b>.
	Once again, right-click on the <i>brtest</i> folder and select
	<b>Commit ...</b> . Provide an initial comment such as
	"Initial Version."<p>
	</ol>

	This sets up the environment for Paul. Wing will work
	in her own workspace by retrieving the files from source control.
	For steps on setting up a new project from source control, see the
	following section in the Eclipse documentation: <b>Workbench User's
	Guide --> Tasks --> Working in the team environment -->
	Checking out a project from a CVS repository</b>.

	<h2>Branch Method</h2>

	When branching off a development stream, it is often advisable to
	rebase before merging the branch back to the main branch. To
	<b>rebase</b> means to merge the contents of the main branch to
	the subbranch. If any conflicts are to be resolved, they are done
	on the subbranch rather than the main branch. If the merge goes
	well, the subbranch is merged to the main branch. After having
	previously resolved all merge conflicts, this last merge would be
	a trivial one. The advantage of taking the extra rebase step is
	that it avoids having conflicts on the main branch.
	<p>
	For this simple example, Paul will simply merge his changes directly
	into the main branch. From the prospective of implementation details,
	the only difference is the merge target. Since this article is
	principally concerned with implementation details of the Eclipse
	branch support using CVS, the simplest branch method is sufficient.

	<h2>Creating the Branch</h2>

	At this point, Paul and Wing have the same version of all files. It
	is now time for Paul to create an independent branch on which to work.
	<p><ol>
	<li>Right-click on the <i>brtest</i> project and select <b>Team -->
	Branch ...</b>. A <i>Create Branch</i> dialog box is displayed.
	Enter a branch name like "p1test." Leave the check box checked for
	<b>Start working in the branch</b>. Notice that a version name is
	automatically filled in for you called "Root_p1test." You may
	choose a different name (so long as it doesn't conflict with an
	existing CVS tag). This will mark where the branch was created.
	It will be used later by the merge editor to determine what has
	changed since branch creation. Click <b>OK</b>.
	<p> <img src="images/makebranch.jpg"
	alt="Dialog for creating a new branch"/>
	<p>
	You should be able to see the result of your branch in two ways. By
	right-clicking the project and selecting <b>Properties</b> and then
	<b>CVS</b>, you should see the <i>p1test</i> in the tag field. If
	you have the CVS label decorations enabled, you'll see the branch
	tag in the navigator view (see below).
	<p><img src="images/branchlist.jpg"
	alt="CVS labels indicating new branch"/>
	<p><table><tr><td>
	<img src="images/tip.gif" width="62" height="13">
	<td>To enable CVS label decorations, go to <b>Window -->
	Preferences</b> and navigate to <b>Workbench --> Label
	Decorations</b>. Check the CVS box.
	</table><p>

	<li>Paul will modify the first file using the <i>p1test</i> branch.
	Open the editor for <code>f1.txt</code>. Change line 4 from "This line
	will be changed later" to "This line has been changed." Save the
	change.<p>

	<li>Open the editor for <code>f3trivial.txt</code>. Change line 4 and
	5 from "This line will be changed by Paul only" to "This line has
	been changed by Paul." Save the change.<p>
	<li>Open the editor for <code>f4conflict.txt</code>. Change lines 4 and
	5 from "This line will be changed by both Paul and Wing" to "This
	line has been changed by Paul." Save the change.<p>

	<li>Right-click on the <i>brtest</i> project and select <b>Team
	--> Synchronize with Repository</b>. In the <b>Outgoing Mode</b>
	view, right-click the <i>brtest</i> project folder and select
	<b>commit</b>. Enter a comment such as "Changes made by Paul." Note
	that for files that have changed, the revision numbers are four digits.
	This is a CVS convention for branched revisions.
	<p><img src="images/p1commit.jpg"
	alt="Paul's CVS label decorations after commit"/>
	<p>

	<li>Now it is Wing's turn. She will make her changes on the main
	branch. Since she already had the main branch loaded into her
	workspace, she doesn't need to perform a branch change. As Wing,
	begin editing <code>f2.txt</code>. Change "This line will be changed
	later" to "This line has been changed." Save the change.<p>

	<li>Edit <code>f3trivial.txt</code> in Wing's workspace. Change lines
	9 and 10 from "This line will be changed by Wing only" to "This
	line has been changed by Wing." Save the change.<p>

	<li>Edit <code>f4conflict.txt</code> in Wing's workspace. Change lines
	4 and 5 from "This line will be changed by Paul and Wing" to "This
	line was changed by Wing." Save the change.<p>

	<li>Commit Wing's changes. Notice her revisions numbers are all two
	digits. That's because her new revisions occur on the main branch.<p>

	</ol>
	<br>

	<h2>The Merge</h2>

	Now it is time for Paul to merge his changes into the main branch
	where Wing's work resides.

	<p><ol start="10"/>
	<li>The first step of the merge is to point
	the workspace to the target branch. In our case, the target
	of the merge is the main branch. To switch the project contents
	to that of the main branch, right-click on the <i>brtest</i>
	project in the Navigator view and select <b>Replace with -->
	Branch or Version ...</b>. You should see a branch selection
	similar to the one below.
	<p><img src="images/branchswitch.jpg"
	alt="Dialog for selecting new branch or version"/>
	<p>

	<li>The <i>p1test</i> branch is the one Paul was working on. To
	switch back to the main branch, select <b>HEAD</b>. This is
	the CVS name for the main branch. Make sure <b>Recurse into
	sub-folders</b> is checked so that all the files in the project
	are replaced with the main branch contents. Then click <b>OK</b>.
	<p>
	The resource view should look like the one below. Notice the
	version numbers correspond to what Wing committed. All the
	version numbers are two digits. The branch name is gone which
	implies the <i>HEAD</i> branch (or main).
	<p><img src="images/afterswitch.jpg"
	alt="Resource view after switching back to main branch"/>
	<p>

	<li>Right-click on the <i>brtest</i> project and select <b>Team -->
	Merge ...</b>. This displays a panel allowing you to choose a "start
	point." For this example, the only start point available is
	<b>Root_p1test</b>, the one
	Paul made by creating the branch. Select it and click <b>Next</b>.
	<p><img src="images/mergestartpoint.jpg"
	alt="Dialog for choosing a merge start point"/>
	<p>

	<li>Next we specify from which branch to pull the changes. Expand
	the <b>Branches</b> node and select <b>p1test</b>. Click
	<b>Finish</b>.<p>
	<p><img src="images/mergewhat.jpg"
	alt="Dialog for selecting choosing a branch to merge"/>
	<p>

	<li>This is where the fun begins. You will be presented with the
	Merge Editor's Structure Compare view with the following merge
	results.
	<p><img src="images/conflict1.jpg"
	alt="Merge tasks."/>
	<p>
	<code>f1.txt</code> was not changed by Wing, so it will come in without
	a problem. But <code>f3trivial.txt</code> and <code>f4conflict.txt</code>
	were each modified by both Paul and Wing. These will require special
	attention during the merge.<p>

	<li>Right-click on the <i>brtest</i> folder and select <b>Update
	from Repository</b>. This action only operates on non-conflicting
	resources (those with no red marks) in the <i>Structure Compare</i>
	view. In our example, it pulls in the changes to <code>f1.txt</code>.
	This should leave your <i>Structure Compare</i> view with only two
	conflicts.<p>

	<li>Right-click <code>f3trivial.txt</code> in the Structure Compare view
	and select <b>Merge changes into Local Copy</b>. Since
	<code>f3trivial.txt</code> was a trivial merge, the merge editor
	automatically copies the changes from the <i>p1test</i> branch into
	our local copy of the main branch. Inspection of <code>f3trivial.txt</code>
	will reveal the changes made by both Paul and Wing.
	<p><table><tr>
	<td><b>Note</b>
	<td>We haven't merged into main yet. That doesn't happen until we
	commit. For now we've just merged into our local copy; hence the
	name of the menu option.
	</table><p>
	You should see an additional file, <code>.#f3trivial.txt</code>, in the
	resource view that isn't under source control. It contains a copy
	of the pre-merge contents for restoration purposes.<p>

	<li>Double-click <code>f4conflict.txt</code> to open the <i>Structure
	Compare</i> view of the merge tool. The left side of the <i>Text
	Compare</i> panel is the local copy of the main branch contents.
	The left side is the <i>brtest</i> branch contents. Since this is
	not a trivial merge, the color red is used to delineate the scope
	of each merge conflict. Blue would be used to denote trivial
	merges.
	<p><img src="images/conflict7.jpg"
	alt="Resolving conflicts with merge editor"/>
	<p>
	We can't resolve this conflict by simply using one side or the
	other. For this case, we edit the text in the left side to say
	"This line has been changed by Paul and Wing." Right-click in
	this same text window and select <b>Save</b>.<p>

	<li>Since we have finished manually merging <code>f4conflict.txt</code>,
	we no longer need to retain it in the <i>Structure Compare</i> view.
	Right-click <code>f4conflict.txt</code> in the <i>Structure Compare</i>
	view and select <b>Remove From View</b>. This only removes it from
	the view, not from the project.<p>

	<li>At this point, the merged copy only exists in our workspace.
	We still need to save it to the CVS respository. Select the
	<i>brtets</i> project in the <i>Navigator</i> view and select
	<b>Team --> Synchronize with Repository</b>. These changes
	should not present any conflicts. Right-click on the <i>brtest</i>
	folder in the <i>Synchronize</i> view and select <b>Commit</b>.
	A suitable comment would be "Merged prtest branch to main."<p>


	<li>A successful merge is often an occasion for a release. In CVS, this amounts
	to tagging all the files with a given tag. In this case, we'll tag it with "p12merge."
	Right-click the <i>brtest</i> project in the <i>Navigator</i> view and select
	<b>Team --> Tag as version ...</b> from its context menu. Enter the name
	"p12merge" for the tag name. Click <b>Finish</b>.
	<p> </ol> <br>
	<h2>Summary</h2>
	In this brief tutorial we illustrated the implementation steps for a simple
	branch and merge scenario. Several files were used to demonstrate different
	types of conflicts that arise during merge activity. In cases where two developers
	edited the same file, we saw the action taken by the <b>Merge changes with Local
	Copy</b> on a file with only trivial conflicts. We saw how to use the merge
	editor to manually resolve non-trivial conflicts. The appendix contains a re-run
	of steps 17 and 18 that use <b>Merge changes with Local Copy</b> on <code>f4conflict.txt</code>.
	<p> After the merge task was complete, we tagged the results to create a release.
	Others can then refer to this release using the name "p12merge." A summary
	of our actions for a single file is obtained by right-clicking on the file
	in the <i>Navigator</i> view and selecting <b>Team --> Show in resource
	history</b>. The resource history for <code>f4conflict.txt</code> is show
	below.
	<p><img src="images/f4history.jpg"
	alt="f4conflict.txt revision history"/>
	<p> We can barely see the <i>Root_p1test</i> tag assigned to revision 1.1, the
	initial version. We see that Paul made changes that were committed to a branch
	while Wing made changes that were committed to main. Finally, the merge resulted
	in revision 1.3, which was tagged for posterity with the label "p12merge."
	<p> For a software developer, the task of merging ranks among status-reports
	and schedule-estimation in terms of loathing. It's not difficult to image
	how the seductively simple "trivial merge" can lead to subtle non-trivial
	problems in code. Eclipse's CVS integration strives to ease this burden by
	putting a friendlier face on branch and merge support.
	<h2>Appendix</h2>
	In steps 17 and 18, we chose to employ the manual merge facilities for the non-trivial
	merge. This appendix describes an alternative to these steps using the automated
	<b>Merge Changes into Local Copy</b> option. Upon encountering a non-trivial
	conflict, this option will insert merge markers in the file. The resource view
	will signify the merge conflict with a special icon marker.
	<p> This alternative works great for simple text files. For source code it can
	result in unexpected compilation behavior if incremental builds are enabled.
	For this reason, the manual merge step was chosen for steps 17 and 18 above.
	These steps are re-worked here using the automated approach for readers that
	prefer this method.
	<p>
	<table>
	<tr>
	<td><img src="images/tip.gif"/>
	<td>It is recommended that <i>incremental compilation</i> be disabled when
	using this method on source code files. This is done from the <b>Windows
	--> Preferences</b> dialog by selecting <b>Workbench</b> on the left
	side and unchecking <b>Perform build automatically on resource modification</b>.
	</table>
	<p>
	<ol start="17">
	<li>Right-click <code>f4conflict.txt</code> and select <b>Merge changes into
	Local Copy</b>. Since this is not a trivial merge, the result will contain
	merge markers that indictate where the conflict occurred. Markers in the
	resource view indicate which files were marged non-trivially.
	<p><img src="images/conflict6.jpg"
	alt="A merge conflict marker"/>
	<p> In the figure above, the non-trivial merge marker appears on <code>f4conflict.txt</code>.
	<p> Note the presence of two additional files not under source control.
	<code>.#f3trivial.txt</code> and <code>.#f4conflict.txt</code> files contain
	copies of the pre-merge contents for restoration purposes.
	<p>
	<li>We now want to resolve the merge conflict for <code>f4conflict.txt</code>
	indicated in the resource view above. Open the <code>f4conflict.txt</code>
	in an editor.
	<p><img src="images/conflict5.jpg"
	alt="Merge markers in a file."/>
	<p> Note the manner in which the merge editor calls attention to different
	versions of the same line. It is up to us to resolve the conflict and
	remove the markers. In this case, we replace the lines between "<code>>>>
	f4conflict.txt</code>" and "<code><<< 1.1.4.1</code>", inclusive,
	to contain "This line has been changed by Paul and Wing." Then save the
	result.
	<p> Notice that saving the result will change the merge conflict marker.
	The assumption is that the save action resolves the conflict.
	<p>
	</ol>
	<br>
	<h2>References</h2>
	Listed below are some references to which one can refer in addition to the Eclipse
	documentation.
	<p>
	<ul>
	<li><i>WebSphere Studio Application Developer Programming Guide</i>, <a href="http://www.redbooks.ibm.com/">http://www.redbooks.ibm.com</a>,
	SG24-6585-00. This reference applies to version 4 of WSAD. The underlying
	Eclipse version is 1.0. Its section on branching and merging provided the
	motivation for writing this article.
	<p>
	<li><i>WebSphere Studio Application Developer Version 5 Programming Guide</i>,
	<a href="http://www.redbooks.ibm.com/"> http://www.redbooks.ibm.com</a>,
	SG24-6957-00. This reference was still in draft stage at the time of this
	writing. It contains a section on branch and merging. The underlying Eclipse
	version is 2.0.
	<p>
	<li><i>Version Management with CVS</i>, Per Cederqvist et al. <a href="http://www.cvshome.org/docs/manual">
	http://www.cvshome.org/docs/manual</a>. This manual is the standard CVS
	reference.
	</ul>
	<p>
	<hr>
	<p><small> <font size="-2">IBM and WebSphere are registered trademarks of IBM
	Corp. in the United States, other countries, or both. </font></small>
	<p>
	</body>
	</html>