| <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> |