| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=windows-1252"> |
| <title>Branching with Eclipse and CVS - Part 2</title> |
| <link rel="stylesheet" href="../article.css" type="text/css" /> |
| <meta name="keywords" |
| content="eclipse, CVS, branching, merge, merging, synchronize, conflict, tagging, version"> |
| </head> |
| |
| <body> |
| <h1>Branching with Eclipse and CVS, Part 2: Rebasing</h1> |
| |
| <div class="summary"> |
| <h2>Summary</h2> |
| <p>In this second part of <i>Branching with Eclipse and CVS</i> we |
| examine an alternative to the merge practice presented in <a |
| href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a>. Instead of only merging changes from |
| the subbranch to the main branch, we rebase the subbranch with changes |
| from the main branch before merging the subbranch back into the main |
| branch. This practice keeps both branches synchronized and keeps most |
| merge activity off the main branch.</p> |
| |
| <div class="author">By Paul Glezen, IBM</div> |
| <div class="copyright">Copyright © 2007 IBM</div> |
| <div class="date">September 5, 2007</div> |
| </div> |
| |
| <div class="content"> |
| <h2>Introduction</h2> |
| As discussed in <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a> of this article, a |
| subbranch is a nice way to isolate development activity from the main |
| branch. But sometimes changes are made to the main branch that should be |
| incorporated into the subbranch. Such an incorporation is called a <i>rebase</i>, |
| since it effectively adjusts the base point on the main branch from |
| which the subbranch was created. Merging in the other direction, from |
| subbranch to main branch, is called a <i>delivery</i>. This is how |
| functionality from the subbranch is delivered to the main branch. |
| |
| <p>As in <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a>, this article will |
| employ a scenario of two programmers, Paul and Wing, working on separate |
| branches of the same project. Paul will branch off the main branch and |
| modify some files while Wing continues work on the main branch, also |
| modifying files. There will be two differences in this second part of |
| the article from the first part.</p> |
| |
| <ol> |
| <li>Paul will synchronize his subbranch with Wing's changes on the |
| main branch before delivery.</li> |
| <li>Wing will perform the delivery herself, rather than Paul |
| switching his workspace between the two branch.</li> |
| </ol> |
| <p>After each rebase-delivery cycle, the two branches will be |
| synchronized. In <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a> the subbranch |
| received none of the main branch changes. The rebase-delivery flow is |
| diagrammed below in the <a href="#scenario">scenario diagram</a>.</p> |
| <p>The process is repeated for a second iteration to demonstrate the |
| so-called <b>merge-again</b> scenario. Work continues on the branch |
| after the first merge; then the branch is merged again later. The |
| merge-again scenario requires that you keep track of when you last |
| merged via tags. This will be demonstrated later in this article.</p> |
| <p>An <a href="#ongoing">alternative</a> is also described that |
| employs Eclipse's CVS Ongoing Merge support. While the method of this |
| article does not depend upon Ongoing Merge support, it is mentioned in |
| steps where it can utilized.</p> |
| <p>The <i><a name="scenario">Scenario Diagram</a></i> below will be |
| referenced throughout this article.</p> |
| <center><img src="images/scenario2.jpg" alt="Scenario Diagram"> |
| </center> |
| <h2>Setup</h2> |
| The sample will use a few text files inside a simple project. In order |
| to carry out the sample yourself, you should already have a working |
| connection to a CVS repository in your Eclipse workspace. |
| <p>If possible, you should considering creating a new repository for |
| this scenario. That's because tags and branches are the central theme of |
| this article. And unlike files in a CVS repository, the tag and branch |
| metadata are difficult to selectively remove if you want to start over. |
| It's much easier to just wipe-out the repository and start with a new |
| one. With a fresh repository, be aware of issues with permissions |
| described in the <a href="#trouble">Troubleshooting</a> section.</p> |
| <p>If you have already done <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a> then |
| you'll want to either start this scenario with a different repository or |
| use different tag and branch names. Otherwise they will conflict with |
| those used in Part 1.</p> |
| <p>The setup instructions below can be expedited through importing |
| the <a href="brtest.zip">brtest.zip</a> into a simple project <b>brtest</b>. |
| </p> |
| |
| <ol type="1"> |
| <li>Create a new simple project called <b>brtest</b>.</li> |
| <li>Add a new file called <code>f1.txt</code>. Add the following |
| contents. |
| |
| <table border="1"> |
| <tbody> |
| <tr> |
| <td><pre>This file will only be edited by Paul
|
|
|
| This line will be changed later.
|
|
|
| This line will be changed after the first merge.
|
|
|
| The rest of this file will remain the same.<br></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| </li> |
| <li>Add a file called <code>f2.txt</code> with the following |
| contents. |
| |
| <table border="1"> |
| <tbody> |
| <tr> |
| <td><pre>This file will only be edited by Wing.
|
|
|
| This line will be changed later.
|
|
|
| This line will be changed after the first merge.
|
|
|
| The rest of this file will remain the same.</pre></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| </li> |
| <li>Add a file called <code>f3trivial.txt</code> with the |
| following contents. |
| |
| <table border="1"> |
| <tbody> |
| <tr> |
| <td><pre>This file will be edited by Paul and Wing.
|
|
|
| This line will be changed by Paul only.
|
|
|
| This line will be changed by Paul only after the first merge.
|
|
|
| This line will be left alone.
|
|
|
| This line will be changed by Wing only.
|
|
|
| This line will be changed by Wing only after the first merge.
|
|
|
| The rest of this file will remain the same.</pre></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| </li> |
| <li>Add a file called <code>f4conflict.txt</code> with the |
| following contents. |
| |
| <table border="1"> |
| <tbody> |
| <tr> |
| <td><pre>This file will be edited by Paul and Wing.
|
|
|
| This line will be changed by both Paul and Wing.
|
|
|
| This line will be changed by both Paul and Wing after the first merge.
|
|
|
| The rest of this file will remain the same.</pre></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>After adding the above files to your project and checking them |
| into CVS, your resource view should look something like the screen shot |
| below.</p> |
| <br> |
| <img alt="Checked in project" src="images/checked_in_project.jpg"><br> |
| </li> |
| </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 with source control, see the following section |
| in the Eclipse documentation: <b>Workbench User's Guide → Tasks |
| → Working in the team environment with CVS → Working with |
| projects shared with CVS</b>. |
| |
| <h2>Merge Method</h2> |
| |
| We'll be demonstrating the rebase-delivery method of merging the |
| subbranch into the main branch. While it requires a few more steps than |
| the merge scenario in <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a>, it provides |
| better synchronization of both branches and keeps most merge work off |
| the main branch. This is illustrated in the <a href="#scenario">Scenario |
| Diagram</a>. |
| <p>An alternative is to simply merge from the subbranch to the main |
| branch without rebasing. Then the merge activity is performed on the |
| main branch. This was the approach used in Part 1 and is fine for some |
| cases.</p> |
| <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. |
| <ol> |
| <li>Right-click on the <b>brtest</b> project and select <b>Team |
| → Branch ...</b>. A dialog is displayed for creating the branch and |
| marking the start-point with a tag (also called a <i>Version Name</i>). |
| Enter a branch name like <b>p1test</b>. Leave the check box checked for |
| <b>Start working in the branch</b>. Notice that a start tag is |
| automatically filled in for you called <b>Root_p1test</b>. This is the |
| first tag labeled in the <a href="#scenario">Scenario Diagram</a>. 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> |
| <p>Since you checked the box to start working in the branch, your |
| workspace should already be configured to work in the branch. You can |
| verify this 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> |
| <p><img src="images/branchlist.jpg" |
| alt="CVS labels indicating new branch" /></p> |
| <div class="note""> |
| <table class="note-table"> |
| <tbody> |
| <tr> |
| <td><img alt="[Note]" src="images/tip.gif"></td> |
| <td>To enable CVS label decorations, go to <b>Window → |
| Preferences</b> and navigate to <b>General → Appearance → |
| Label Decorations</b>. Check the 'CVS' box.</td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| </li> |
| <li>This step begins the work represented as the blue box labeled |
| <b>PD1</b> in the <a href="#scenario">Scenario Diagram</a>. Paul will |
| modify the first file using the <i>p1test</i> branch. Open the editor |
| for <code>f1.txt</code>. Change line 3 from "This line will be changed |
| later" to "This line changed in iter1." Save the change.</li> |
| <li>Open the editor for <code>f3trivial.txt</code>. Change line 3 |
| from "This line will be changed by Paul only" to "This line changed by |
| Paul in iter1." Save the change.</li> |
| <li>Open the editor for <code>f4conflict.txt</code>. Change line 3 |
| from "This line will be changed by both Paul and Wing" to "This line |
| changed by Paul in iter1." Save the change.</li> |
| <li>Right-click on the <b>brtest</b> project and select <b>Team |
| → Synchronize with Repository</b>. In the <b>Outgoing Mode</b> view, |
| right-click the <b>brtest</b> project folder and select <b>Commit</b>. |
| Enter a comment such as "First iteration 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> |
| <p>This commit is represented by the first red circle on the <i>p1test</i> |
| branch of the Scenario Diagram. Now it is Wing's turn. Her work is |
| represented in the <a href="#scenario">Scenario Diagram</a> by the blue |
| box labeled <b>WD1</b>.</p> |
| |
| </li> |
| <li>Wing will make her changes in the main branch. In her |
| workspace she connects to CVS as "wing" to checkout the <b>brtest</b> |
| project from CVS. |
| <p><img src="images/wingcheckout.jpg" alt="" /></p> |
| She chooses the <b>brtest</b> under <b>HEAD</b>, the moniker CVS uses |
| to designate the main branch. |
| <p>Since Wing has 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 changed by Wing |
| in iter1." Save the change.</p> |
| |
| </li> |
| <li>Edit <code>f3trivial.txt</code> in Wing's workspace. Change |
| line 9 from "This line will be changed by Wing only" to "This line |
| changed by Wing in iter1." Save the change.</li> |
| <li>Edit <code>f4conflict.txt</code> in Wing's workspace. Change |
| line 3 from "This line will be changed by Paul and Wing" to "This line |
| changed by Wing in iter1." Save the change.</li> |
| <li>Commit Wing's changes with a comment like "First iteration |
| changes by Wing". Note her revisions numbers are all two digits (e.g. |
| 1.2). That's because her new revisions occur on the main branch. This |
| commit is represented by the first red circle on the main branch in the |
| <a href="#scenario">Scenario Diagram</a>.</li> |
| <li>Wing is finished development for this iteration. So she will <a |
| name="howtotag">tag</a> this milestone with <b>W1</b>. Right-click the |
| <b>brtest</b> project and select <b>Team → Tag as Version ...</b>. |
| In the dialog that arises, enter <b>W1</b> for the tag name and click <b>OK</b>. |
| This corresponds to the <b>W1</b> tag in the <a href="#scenario">Scenario |
| Diagram</a>. |
| <div class="note""> |
| <table class="note-table"> |
| <tbody> |
| <tr> |
| <td><img alt="[Note]" src="images/tip.gif"></td> |
| <td>To to verify a tag was created, change to the CVS |
| Repository view and expand <b>Versions → brtest.</b> The <b>W1</b> |
| tag should be visible.</td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </li> |
| </ol> |
| |
| <h2>The Merge</h2> |
| Now it is time for Paul to merge Wing's changes from the main branch |
| into the p1test branch. |
| <ol start="11"> |
| <li>Since a merge has the potential to get ugly, it's a good idea |
| to tag the completion of work labeled <b>PD1</b> in the <a |
| href="#scenario">Scenario Diagram</a>. In Paul's workspace, which is |
| still pointed to the <b>p1test</b> branch, add the <b>P1</b> tag in the |
| same manner that Wing added <b>W1</b> <a href="#howtotag">earlier</a>. |
| |
| </li> |
| <li>We begin the rebase by right-clicking the <b>brtest</b> |
| project and selecting <b>Team → Merge</b>. |
| <p>Click <b>Browse</b> for the <b>end-tag</b> field and select <b>HEAD</b>. |
| This represents the main branch.</p> |
| <p>In the <b>start tag</b> field, click browse and select <b>Root_p1test</b> |
| from the list of tags.</p> |
| <p>An alternative to using the browse button each time is to summon |
| the Content Assist in either of the end or start tag fields with the |
| Ctrl + Space Bar keys while the cursor is in the field.</p> |
| <p><img src="images/mergeDialog5.jpg" alt="" /></p> |
| <p>As for the rest of the panel, select <b>Preview the merge in |
| the synchronize view</b> to take advantage of Eclipse CVS support for |
| resolving merge conflicts. Also check <b>Merge non-conflicting |
| changes and only preview conflicts</b>. Otherwise we will have to merge the |
| non-conflicting changes manually. We will use these settings for all |
| our merges in this article.</p> |
| |
| </li> |
| <li>Click <b>Finish</b>. You should see the following message. |
| <p><img src="images/mergeFail1.jpg" alt="" /></p> |
| <p>This is not as dire as it might seem. It just means there are |
| conflicts we have to resolve. Click <b>OK</b> to continue.</p> |
| |
| </li> |
| <li>This is where the fun begins. You will be presented with the |
| following Synchronize view. |
| <p><img src="images/sync01.jpg" alt="" /></p> |
| <p>Note that only the conflict appears. The trivial merges were |
| performed automatically as can be seen by the change markers in front |
| of files <tt>f2.txt</tt> and <tt>f3trivial.txt</tt> in the Navigator |
| view.</p> |
| <p><img src="images/sync02.jpg" alt="" /></p> |
| <p>Opening <tt>f3trivial.txt</tt> shows that indeed the automatic |
| merge does the right thing when the same line isn't changed by separate |
| parties.</p> |
| <p><img src="images/sync03.jpg" alt="" /></p> |
| <p>As for the conflict, double-click <tt>f4conflict.txt</tt> in the |
| Synchronize view. The <a name="resolve">conflict editor</a> displays |
| the following.</p> |
| <p><img src="images/sync04.jpg" alt="" /></p> |
| |
| </li> |
| <li>The problem is the line highlighted in red. Both Paul and Wing |
| changed it. There is no way for the automatic merge mechanism to |
| determine what to do. (In some cases, even humans have a hard time.) In |
| this case, we determine the line should read <pre>This line changed by Paul and Wing in iter1 during merge.</pre> |
| Change this in the left-hand side of the conflict editor. The left-hand |
| side is effectively a text editor. The right-hand side is a read-only |
| view of the other conflicting party. |
| <p>Right-click the left-hand editor and choose <b>Save</b> once the |
| change is made.</p> |
| <div class="note""> |
| <table class="note-table"> |
| <tbody> |
| <tr> |
| <td><img alt="[Note]" src="images/tip.gif"></td> |
| <td>Now would be the time to pin the Merge Synchronization view |
| in order to take advantage of the <a href="#ongoing">Ongoing |
| Merge</a> support provided by Eclipse. This feature is described as an |
| alternative at the end of this article.</td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| </li> |
| <li>Even after the save, the entry in the conflict editor remains |
| red. That's because from the Eclipse SCM perspective, there is still a |
| conflict. It's just a conflict with some extra changes. We have to |
| explicitly inform the Eclipse SCM that we have indeed resolved the |
| conflict and that from this point onward, the changes to the local copy |
| should be interpreted relative to the contents of the left-side. |
| |
| <center><img src="images/markmerged.jpg" alt="" /></center> |
| <p>This is done by right-clicking the file in the Synchronize view |
| and selecting <b>Mark as Merged</b>. Do this now and notice there are |
| no more conflicts.</p> |
| <div class="note""> |
| <table class="note-table"> |
| <tbody> |
| <tr> |
| <td><img alt="[Note]" src="images/tip.gif"></td> |
| <td>In Eclipse 3.3, the <b>Mark as Merged</b> action is also |
| available from the context menu of the compare editor.</td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <p>This completes the merge labeled <b>M1</b> in the <a |
| href="#scenario">Scenario Diagram</a>.</p> |
| |
| </li> |
| <li>Commit the changes with a comment such as "Merged HEAD into |
| brtest for iteration 1."</li> |
| <li>A successful merge is an important milestone. Tag this version |
| with <b>PM1</b> to correspond with the label in the <a href="#scenario">Scenario |
| Diagram</a>.</li> |
| <li>Wing will now perform the merge from <b>brtest</b> to the main |
| branch since she owns the main branch. The version tagged <b>PM1</b> |
| contains all the work from <b>PD1</b> and <b>WD1</b> plus whatever |
| merge work was necessary in <b>M1</b>. The <b>M1</b> modifications may |
| conflict with her contents at <b>W1</b>. But this is fine since <b>M1</b> |
| was a conflict resolution. |
| <p>In Wing's workspace, which is still pointing to the main branch, |
| right-click on <b>brtest</b> and select <b>Team → Merge ... </b>. |
| </p> |
| |
| </li> |
| <li>The merge dialog should be familiar by now. Browse for <b>p1test</b> |
| for the <b>end tag</b>. This automatically populates the <b>start |
| tag</b> with <b>Root_p1test</b>. Be sure to check <b>Merge |
| non-conflicting changes</b>. |
| <p><img src="images/mergeDialog6.jpg" alt="" /></p> |
| |
| </li> |
| <li>Click <b>Finish</b> on the merge dialog. The resulting |
| conflict is expected since the resolution in <b>M1</b> was different |
| from both the <b>P1</b> and <b>W1</b> versions. |
| <p><img src="images/mergeDialog7.jpg" alt="" /></p> |
| <p>Pin this synchronization view if you wish to take advantage of |
| Eclipse's <a href="#ongoing">Ongoing Merge</a> support.</p> |
| |
| </li> |
| <li>Right-click the <tt>f4conflict.txt</tt> in the Synchronize |
| view and select <b>Overwrite</b>. This overwrites the working copy of |
| the main branch with the properly merged copy from the <b>brtest</b> |
| branch. This will remove the conflict marker.</li> |
| <li>Commit the result of the merge into the main branch with a |
| comment like "Merged the rebase results from brtest."</li> |
| <li>Tag this result with <b>WM1</b>. This corresponds to the <b>WM1</b> |
| tag in the <a href="#scenario">Scenario Diagram</a>.</li> |
| </ol> |
| |
| This completes the first iteration. Both branches are now synchronized. |
| This sets the stage for the next section, the merge-again scenario. |
| |
| <h2>Merge Again</h2> |
| This is where Paul and Wing each continue to work on their own branch |
| and synchronize again at a later time. These steps are part of <i>Iteration |
| 2</i> in the <a href="#scenario">Scenario Diagram</a>. The file editing is |
| very similar to <i>Iteration 1</i>. More emphasis will be placed on the |
| merging. |
| <p>The following steps begin in Paul's workspace, which should still |
| be pointing to the <b>p1test</b> branch. If this is not the case, switch |
| to the <b>p1test</b> branch through the usual method of right-clicking |
| the project and selecting <b>Replace with → Another Branch or |
| Version</b>.</p> |
| |
| <ol> |
| <li>Open <tt>f1.txt</tt>. Change line 5 to read "This line changed |
| in iter2."</li> |
| <li>Open <tt>f3trivial.txt</tt> and change line 5 to read "This |
| line changed by Paul in iter2."</li> |
| <li>Open <tt>f4conflict.txt</tt> and change line 5 to read "This |
| line changed by Paul in iter2.".</li> |
| <li>Save the changes. This completes the work represented by <b>PD2</b> |
| in the <a href="#scenario">Scenario Diagram</a>. Commit these changes |
| using a comment such as "Second iteration changes made by Paul."</li> |
| <li>Tag this state of the project with <b>P2</b>. Refer to a <a |
| href="#howtotag">previous tag step</a> for a refresher on creating |
| tags if you need one. |
| <p>Wing will continue her work in her own workspace. It should |
| already be pointing to the main branch. This work is denoted by <b>WD2</b> |
| on the scenario diagram.</p> |
| |
| </li> |
| <li>In Wing's workspace, open <tt>f2.txt</tt> and edit line 5 to |
| read "This line changed by Wing in iter2.".</li> |
| <li>Open <tt>f3trivial.txt</tt> and change line 11 to read "This |
| line changed by Wing in iter2."</li> |
| <li>Open <tt>f4conflict.txt</tt> and change line 5 to read "This |
| line changed by Wing in iter2."</li> |
| <li>Save the changes. This completes the work represented by <b>WD2</b> |
| in the <a href="#scenario">Scenario Diagram</a>. Commit these changes |
| using a comment such as "Second iteration changes made by Wing."</li> |
| <li>Tag this state of the project with <b>W2</b>, referring to a <a |
| href="#howtotag">previous tag step</a> if needed. |
| <p>Paul and Wing have both finished their <i>Iteration 2</i> work. |
| It is now time for rebase-and-merge sequence. Switch back to Paul's |
| workspace for the rebase.</p> |
| |
| </li> |
| <li>From Paul's workspace, right-click the <b>brtest</b> project |
| and select <b>Team &rarr Merge</b>. This will begin the Merge Dialog.</li> |
| <li>For the <b>end tag</b> field, click <b>Browse</b>. Choose the |
| <b>HEAD</b> which represents the main branch as in the figure below. |
| <p><img src="images/mergeDialog8.jpg" alt="" /></p> |
| |
| </li> |
| <li><img src="images/mergeDialog9.jpg" align="right" hspace="50" |
| alt="" /> Click the <b>Browse</b> button for the <b>start tag</b> |
| field. From the list of tags, select <b>WM1</b>. (Remember to click <b>Refresh |
| Tags</b> if you don't see it in the list. This applies to both the <b>Browse</b> |
| button and the Content Assist.) |
| <p>This differs from the original merge where we simply choose the |
| original branch point. Since we've already merged and synchronized |
| once, we only want to merge the changes since the last synchronization. |
| <b>We can only do this if we've tagged the last synchronization.</b> |
| That's why tagging is very important after every merge.</p> |
| <p>If you pinned the Merge Synchronization view from last time to |
| take advantage of the <a href="#ongoing">Ongoing Merge</a> support, you |
| can continue to use the <b>Root_p1test</b> as the start tag.</p> |
| <p>Be sure to check <b>Merge non-conflicting changes</b>. This |
| saves us work during the conflict resolution process. <br clear="all" /> |
| </p> |
| |
| </li> |
| <li>Click <b>Finish</b> to start the merge. You'll be left with |
| the usual conflict in <tt>f4conflict.txt</tt>. <a href="#resolve">Resolve</a> |
| it as you have in past merges. That is, |
| |
| <ol style=""> |
| <li>Resolve the conflict by editing the left panel.</li> |
| <li>Save the left panel.</li> |
| <li>Mark as merged.</li> |
| </ol> |
| <p>This completes the <b>M2</b> merge activity denoted in the <a |
| href="#scenario">Scenario Diagram</a>.</p> |
| |
| </li> |
| <li>Commit the merge with a comment such as "Merged from WM1 of |
| HEAD into brtest for iteration 2."</li> |
| <li>Tag this result as <b>PM2</b>. |
| <p>At this point, Paul has all his changes as well as the changes |
| Wing made during the <b>WD2</b> activity (suitably merged where there |
| were conflicts). It's now time for Wing to benefit both from Paul's <b>PD2</b> |
| as well as the merge toil performed in <b>M2</b>.</p> |
| |
| </li> |
| <li>In Wing's workspace, right-click the <b>brtest</b> project and |
| select <b>Team &rarr Merge</b>. This starts the merge dialog with which |
| we are now familiar.</li> |
| <li><img src="images/mergeDialog10.jpg" align="right" hspace="50" |
| alt="" /> Choose <b>p1test</b> for the branch. The Eclipse CVS |
| support may auto-fill <i>Root_p1test</i>. But this is no longer the one |
| we want. Rather, we want to begin the merge from <b>PM1</b>, which was |
| the last point on p1test at which we synchronized. |
| <p>If pinned the Merge Synchronization view from the last merge, |
| you may continue to use the <b>Root_p1test</b> as the start tag. This |
| is because the pinned view remembers your previous merges and so |
| doesn't require you to tell it explicitly.</p> |
| <p>Click <b>Finish</b> to effect the merge. <br clear="all" /> |
| </p> |
| |
| </li> |
| <li>As in the first merge, the only conflicts expected are those |
| already resolved in the rebase. So we simply right-click the <tt>f4conflict.txt</tt> |
| that appears in the Synchronize view and select <b>overwrite</b>.</li> |
| <li>Commit the changes with a comment like "Merged the rebase |
| results from iteration2 on brtest into HEAD.</li> |
| <li>Finally, tag the result with <b>WM2</b> for use by any future |
| merges.</li> |
| </ol> |
| |
| <h2>Summary</h2> |
| In this second part of our branching tutorial, we introduced a procedure |
| for the rebase technique. There are a few more steps than in <a |
| href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a>, but it provides synchronization across |
| both branches. Tagging merge milestones played an important role. |
| <p>It's educational to review the CVS history for a few files in our |
| scenario. The CVS history for a file is available by right-clicking on |
| the file and selecting <b>Team → Show History</b>. The screen-shot |
| below captures the CVS history for <tt>f1.txt</tt>. Since only Paul |
| changed it, things were simple.</p> |
| <p><img src="images/f1history2.jpg" alt="" /></p> |
| <p>Note that multiple tags are assigned to a single version of the |
| file. This is because the file version didn't change from one tag to |
| another.</p> |
| <p>The screen-shot below show the CVS history for <tt>f3trivial.txt</tt>. |
| Since both Paul and Wing were changing <tt>f3trivial.txt</tt> throughout |
| the scenario, it's tags are spread out across the versions.</p> |
| <p><img src="images/f3history2.jpg" alt="" /></p> |
| <p>With the exception of the initial creation, you can see how |
| Paul's version numbers are four digits because he was working on a |
| subbranch. Wing's versions are two digits because she was working on the |
| main branch.</p> |
| <p>One final note on the CVS History view. The screen-shot above was |
| taken from Paul's workspace, which is still pointing to the <b>brtest</b> |
| branch. For the <b>brtest</b> branch, revision 1.1.2.4 is the latest. |
| That's why revision 1.1.1.4 is in bold instead of revision 1.5, which |
| seems to be the latest version in the History view. If the screen-shot |
| had been taken from Wing's workspace, revision 1.5 would have been in |
| bold.</p> |
| <p>The simplicity of our example made tagging seem appropriate after |
| each commit. That's because we simplified the development activity |
| denoted by the blue boxes in the <a href="#scenario">Scenario |
| Diagram</a>. In practice, these blue boxes would themselves contain several |
| commits without tags. Tags are most commonly used to denote</p> |
| |
| <ol> |
| <li>milestones for builds</li> |
| <li>points from which one would like to recover.</li> |
| </ol> |
| <p>Eclipse CVS support provides a feature to replace the latest |
| version of a branch with any tagged previous version of the branch. This |
| basically allows you to "back out" commits; <b>but only to a |
| previously tagged version.</b> That's why we tag before merges in our |
| scenario. We don't need the tags for future merging. But we may regret a |
| merge even after the commit and want to restore the state of the branch |
| before the merge.</p> |
| <h2>An Alternative - <a name="ongoing">Ongoing Merges</a></h2> |
| The Eclipse <i>CVS Merge Synchronization</i> view provides support for <i>Ongoing |
| Merges</i>. This works by pinning the Merge Synchronization view so that it |
| continues to be present (behind the scenes) and remembers what has |
| already been merged. So in the merge-again scenario, if we had had the |
| Merge Synchronization view pinned since the first merge, then we could |
| have left the start tag with the default <b>Root_p1test</b>. The CVS |
| Merge Synchronization view would have remembered the earlier merge |
| between <b>Root_p1test</b> and <b>P1</b> and not tried to re-apply those |
| changes. |
| <p>The <i>Ongoing Merge</i> support works well, but has its |
| limitations. In <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article1.html">Part 1</a> of this article, Paul |
| did the first merge while Wing did the second. Unless the same workspace |
| is involved throughout the merge scenario, Ongoing Merge support is not |
| feasible. But in practice, one generally does use the same workspace for |
| merges, and so Ongoing Merge support is a great help. In the scenario |
| for this article, Paul's workspace was always used for rebase merges, |
| while Wing's workspace was always used for deliveries. So the Ongoing |
| Merge support would have worked fine in this case and hence was listed |
| as an optional step. Ongoing Merge support provides these additional |
| features.</p> |
| |
| <ol> |
| <li>Multiple Merge Synchronization views can be pinned. This |
| enables one to coordinate deliveries from multiple branches.</li> |
| <li>Merge Synchronization may be scheduled. You can obtain the |
| following configuration panel by clicking the Merge Synchronization |
| menu button (the down arrow) and selecting <b>Schedule ...</b>. |
| <p><img src="images/configMergeSync.jpg" alt="" /></p> |
| <p>So you become aware of work committed to other branches on a |
| regular basis.</p> |
| </li> |
| </ol> |
| <p>The Ongoing Merge support should not entirely supplant tagging. |
| The merge points should still be tagged for milestone purposes and in |
| case the pinned Merge Synchronization view somehow becomes unavailable. |
| The Ongoing Merge support is mentioned in the Eclipse Help under <b>Workbench |
| User's Guide → Reference → Team Support with CVS → CVS |
| Merge Synchronization</b>.</p> |
| <h2><a name="trouble">Troubleshooting</a></h2> |
| This section contains solutions to problems that may arise during your |
| experimentation with the Eclipse CVS support. |
| |
| <h3>Permissions</h3> |
| A user must have write permission to the CVS Server's copy of a file in |
| order to commit. Without these permissions, you will receive an error |
| dialog like the one below. |
| <p><img src="images/commitFail1.jpg" alt="" /></p> |
| <p>This can be resolved through adjusting the permissions on the |
| server-side copy of the file.</p> |
| <p>You may also see the following error message when you try to tag. |
| </p> |
| <p><img src="images/tagFail1.jpg" alt="" /></p> |
| <p>This means the tag request was issued by someone without write |
| authority on the tag file, <tt>CVSROOT/val-tags</tt>. All users that tag |
| releases must have write permission to this file.</p> |
| <h3>Missing Tags</h3> |
| |
| Sometimes you are asked to choose a tag or branch from a dialog, but the |
| tag or branch is missing from the list. If the tag exists but you don't |
| see it, the list probably needs to be refreshed. Most such dialogs have |
| a <b>Refresh Tags</b> button for this purpose. |
| <p>Likewise, in the CVS Explorer view, you can right-click most |
| nodes and select <b>Refresh</b>. All nodes below the selected node will |
| be refreshed also.</p> |
| <h2>References</h2> |
| Listed below is the standard reference to which one can refer in |
| addition to the Eclipse documentation. |
| |
| <ul> |
| <li><i>Version Management with CVS</i>, Per Cederqvist et al. <a |
| href="http://ximbiot.com/cvs/manual"> |
| http://ximbiot.com/cvs/manual</a>. This manual is the standard CVS |
| reference.</li> |
| <li><i>CVS Best Practices</i>, Vivek Venugopalan 2002 <a |
| href="http://www.tldp.org/REF/CVS-BestPractices/html/">html</a>, <a |
| href="http://www.tldp.org/REF/CVS-BestPractices/CVS-BestPractices.pdf">pdf</a>(75k) |
| </li> |
| </ul> |
| |
| <h2>Useful plug-ins</h2> |
| <ul> |
| <li>Version Trees provides a graphical view of the versions, |
| branches and tags for a file. <a |
| href="http://versiontree.sourceforge.net/">http://versiontree.sourceforge.net/</a> |
| </li> |
| <li>TortoiseCVS provides a Windows Explorer extension for working |
| with CVS. <a href="http://www.tortoisecvs.org">http://www.tortoisecvs.org</a> |
| </li> |
| </ul> |
| </div> |
| </body> |
| </html> |