| <!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 1</title> | |
| <link rel="stylesheet" href="../article.css" type="text/css" /> | |
| <meta name="keywords" | |
| content="eclipse, CVS, branching, merge, merging, synchronise, conflict, tagging, version"> | |
| </head> | |
| <body> | |
| <h1>Branching with Eclipse and CVS, Part 1: The Basics</h1> | |
| <div class="summary"> | |
| <h2>Summary</h2> | |
| <p>This article presents a brief branch-and-merge scenario designed | |
| to quickly illustrate some branch-and-merge features of Eclipse's CVS | |
| support. We assume the reader already appreciates the value of branching | |
| and merging in a source control environment. This article walks through | |
| a step-by-step scenario illustrating simple branch-and-merge operations | |
| using Eclipse-based IDEs with CVS as the source control mechanism.</p> | |
| <p>For a branch-and-merge scenario that incorporates rebasing, | |
| please refer to <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article2.html">Part 2</a> of this article. This | |
| article is <b>not</b> a prerequisite for Part 2. Rather, Part 1 provides | |
| simpler branch-and-merge techniques.</p> | |
| <div class="author">By Paul Glezen, IBM and James Neethling</div> | |
| <div class="copyright">Copyright © 2007 IBM</div> | |
| <div class="date">September 5, 2007</div> | |
| </div> | |
| <div class="content"> | |
| <h2>Introduction</h2> | |
| In any source control management (SCM) environment, branching is a | |
| powerful mechanism for controlled isolation. Despite being a simple | |
| concept, controlled isolation is often avoided in practice because of | |
| its implementation complexities. This article demonstrates how to | |
| perform branching with Eclipse's CVS support. The Eclipse on-line | |
| documentation covers this topic, but does not provide an end-to-end | |
| scenario. The intended audience is software development professionals | |
| with an appreciation for the roles of branch and merge techniques in | |
| SCM. | |
| <p>This article will employ a scenario 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. This 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>The <i><a name="scenario">Scenario Diagram</a></i> below will be | |
| referenced throughout this article.</p> | |
| <center><img src="images/scenario1.jpg" | |
| alt="Elementary Branch Concept"></center> | |
| <p><a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article2.html">Part 2</a> of this article adds the <i>rebase</i> | |
| operation to the scenario.</p> | |
| <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. If you do create your own CVS repository for this article, see the | |
| <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article2.html#trouble">Troubleshooting section in Part 2</a> | |
| for setting the necessary permissions on a new CVS repository.</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> | |
| When branching off a development stream, it is often advisable to rebase | |
| before merging the subbranch 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 advantages of taking the extra | |
| rebase step is that it avoids having conflicts on the main branch and it | |
| keeps the subbranch synchronized with the main branch. This is the | |
| approach taken in <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article2.html">Part 2</a>. | |
| <p>In this article, our primary focus is the merge mechanism of | |
| Eclipse's CVS support, not the particular branching strategy. So here in | |
| Part 1, we stick with the branch method illustrated in the <a | |
| href="#scenario">Scenario Diagram</a>.</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.</p> | |
| </li> | |
| <li>(<i>Optional <a name="howtotag">tag step</a>, only | |
| required for the merge-again scenario</i>) Paul is finished development for | |
| this iteration. So he will <a name="howtotag">tag</a> this milestone | |
| with <b>P1</b>. This tag will represent the base-point for the | |
| merge-again scenario. Right-click the <b>brtest</b> project and select | |
| <b>Team → Tag as Version ...</b>. In the dialog that arises, enter | |
| <b>P1</b> for the tag name and click <b>OK</b>. This corresponds to the | |
| <b>P1</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>P1</b> | |
| tag should be visible.</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p>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>(<i>Optional tag step, not required anywhere.</i>) Since it is | |
| a good practice to tag a milestone or a recovery point, Wing tags this | |
| point with <b>W1</b> in the same manner as the in the <a | |
| href="#howtotag">previous tag</a>. It's a good idea to tag right | |
| before merging something into your branch so you can recover it more | |
| easily even after a commit. | |
| <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 his changes into the main branch where | |
| Wing's work resides. This is designated with the <b>M1</b> diamond in | |
| the <a href="#scenario">Scenario Diagram</a>. | |
| <ol start="12"> | |
| <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 <b>brtest</b> 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. (If you performed the optional tagging steps, | |
| you may see some of those under <i>Versions</i>. You may have to click | |
| <b>Refresh Tags</b> to see them all.) | |
| <p><img src="images/branchswitch2.jpg" | |
| alt="Dialog for selecting new branch or version" /></p> | |
| </li> | |
| <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. 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> | |
| <p><img src="images/afterswitch.jpg" | |
| alt="Resource view after switching back to main branch" /></p> | |
| </li> | |
| <li>Right-click on the <b>brtest</b> project and select <b>Team | |
| → Merge ...</b>. Click the <b>Browse</b> button next to the <b>Branch | |
| or version to be merged</b> field. Choose the <b>p1test</b> branch from the | |
| <b>Choose End Tag</b> dialog box. If you don't see the branch, you may | |
| have to click <b>Refresh tags</b>. Click <b>OK</b>. | |
| <p><img src="images/mergestartpoint2.jpg" | |
| alt="Dialog for choosing a merge start point" /></p> | |
| </li> | |
| <li>The start tag should be filled automatically with <b>Root_p1test</b>. | |
| In this case, the dialog anticipated correctly. For this merge, we have | |
| elected <b>not</b> to check the <b>Merge non-conflicting changes</b> | |
| checkbox. In the merge-again scenario, we will check it and compare the | |
| difference. Click <b>Finish</b>. | |
| <p><img src="images/mergewhat3.jpg" | |
| alt="Dialog for selecting choosing a branch to merge" /></p> | |
| <div class="note"> | |
| <table class="note-table"> | |
| <tbody> | |
| <tr> | |
| <td><img alt="[Note]" src="images/tip.gif"></td> | |
| <td>Instead of browsing for the end tag, you could have taken | |
| advantage of Content Assist (through Ctrl + Space Bar) as indicated | |
| by the tiny light bulb next to the field.</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| </li> | |
| <li>This is where the fun begins. You will be presented with the <i>Synchronize</i> | |
| view with the following merge results: | |
| <p><img src="images/conflict1.jpg" alt="Merge tasks." /></p> | |
| <p><code>f1.txt</code> was not changed by Wing, so it will be | |
| locally updated without a problem. But <code>f3trivial.txt</code> and <code>f4conflict.txt</code> | |
| were each modified by both Paul and Wing and are indicated with the red | |
| double-headed arrows.</p> | |
| </li> | |
| <li>Right-click on the <b>brtest</b> folder and select <b>Merge</b>. | |
| CVS will attempt to work out if there are any changes that are in | |
| conflict between Paul's local version and the repository. In our | |
| example, it updates <code>f1.txt</code> as well as <code>f3trivial.txt</code> | |
| as it was able to resolve the conflicts there. However, <code>f4trivial.txt | |
| </code>presents it with a challenge and Eclipse will alert you that it was not | |
| able to automatically merge the changes. | |
| <center><img src="images/threat1.jpg" alt="" /></center> | |
| <p>As ominous as this appears, it's merely a reminder that we have | |
| to resolve some merge conflicts because they were not auto-mergeable. | |
| We could have avoided the spectacle of this message if we had simply | |
| checked the <b>Merge non-conflicting changes</b> checkbox.</p> | |
| <p>Now lets resolve the conflicts.</p> | |
| </li> | |
| <li>Double-click <code>f4conflict.txt</code> in the <i>Synchronize</i> | |
| view to open the <i>Compare</i> editor of the merge tool. The left side | |
| of the <i>Text Compare</i> panel is the local copy of the main branch | |
| contents. The right side is the <b>brtest</b> 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/conflict8.jpg" | |
| alt="Resolving conflicts with merge editor" /></p> | |
| <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 (local file) to | |
| say "This line changed by Paul and Wing in iter1." Right-click in this | |
| same text window and select <b>Save</b>.</p> | |
| </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 <i>Synchronize</i> | |
| 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>We have now completed merging the changes.</p> | |
| </li> | |
| <li>At this point, the merged copy only exists in our workspace. | |
| We still need to commit it to the CVS repository. Select the <b>brtest</b> | |
| 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 <b>brtest</b> folder in the <i>Synchronize</i> | |
| view and select <b>Commit</b>. A suitable comment would be "Merged | |
| p1test branch up to P1 into main." | |
| </li> | |
| <li>Tag the result as <b>WM1</b>. This corresponds to the <b>WM1</b> | |
| tag in the <a href="#scenario">Scenario Diagram</a>. | |
| </li> | |
| <li>Be sure to update Wing's workspace with the results of the | |
| merge.</li> | |
| </ol> | |
| <h2>Check Point</h2> | |
| This completes the branch-and-merge scenario for Iteration 1. The next | |
| section continues with a merge-again example. But let's pause for a | |
| moment to review what we have done. | |
| <p>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 that CVS was able to | |
| automatically merge trivial changes. Where manual intervention was | |
| required, we saw how to use the merge editor to manually resolve these | |
| conflicts.</p> | |
| <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 History</b>. The history for <code>f4conflict.txt</code> is | |
| shown below.</p> | |
| <p><img src="images/f4history2.jpg" | |
| alt="f4conflict.txt revision history"></p> | |
| <p>We can see that the <i>Root_p1test</i> tag is 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 <b>WM1</b>.</p> | |
| <p>For many cases, this may be the only merge scenario you need. It | |
| is certainly sufficient for short-lived branches that introduce a new | |
| feature, test it, and then merge it into the main branch. For longer | |
| running branches where multiple merges are required, the following | |
| merge-again scenario is useful.</p> | |
| <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> using <b>Team | |
| → Tag as Version</b>. This corresponds to the <b>P2</b> tag in the <a | |
| href="#scenario">Scenario Diagram</a>. | |
| <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 a <a | |
| href="#howtotag">previous tag step</a> if needed. | |
| <p>Paul and Wing have both finished their <i>Iteration 2</i> work. | |
| This time Wing will perform the merge herself from within her own | |
| workspace.</p> | |
| </li> | |
| <li>As Wing, in her workspace, click the <b>brtest</b> project and | |
| select <b>Team → Merge</b>. | |
| </li> | |
| <li>Click <b>Browse</b> next to the <b>end tag</b> field. Under <b>Branches</b>, | |
| select <b>p1test</b>. If the branch is not visible yet, select <b>Refresh | |
| Tags</b>. (Or you can simply use Content Assist.) Click <b>OK</b>. | |
| <p>Notice that the <b>start tag</b> is populated already. But this | |
| is not the value we want. Upon review of the <a href="#scenario">Scenario | |
| Diagram</a> we see that all we want to merge into main are the changes in | |
| the blue box labeled <b>PD2</b>. But if we specify <b>Root_p1test</b> | |
| in the <b>start tag</b> field, we would also be merging in changes from | |
| the blue box labeled <b>PD1</b>. The <b>PD1</b> changes were already | |
| merged during Iteration 1. Using this default start tag would cause the | |
| same changes to be applied twice. This should be avoided even though it | |
| still works in many cases.</p> | |
| <p>To apply only the changes since the last merge, we want to | |
| specify the <b>P1</b> tag. This encapsulates precisely the <b>PD2</b> | |
| development work.</p> | |
| </li> | |
| <li>Click <b>Browse</b> next to the <b>start tag</b> field and | |
| select <b>P1</b> from the list of tags. Click <b>OK</b>. | |
| </li> | |
| <li>Be sure to check <b>Merge non-conflicting changes</b> so that | |
| the auto-mergeable differences are applied automatically. | |
| <p><img src="images/mergeDialog11.jpg" alt="" /></p> | |
| <p>Click <b>Finish</b>.</p> | |
| <p>You should see the usual <b>Merge Failure</b> dialog indicating | |
| that a non-auto-mergeable conflict was encountered. Click <b>OK</b> so | |
| we can get to work on resolving the conflict.</p> | |
| </li> | |
| <li>The <i>Synchronize</i> view shows that, like before, <code>f4conflict.txt</code> | |
| is the only file with a conflict. Double-click it to view the conflict | |
| in the Text Compare editor. Shown below is the most important | |
| screen-shot of the merge-again scenario. | |
| <p><img src="images/conflict4.jpg" alt="" /></p> | |
| <p>Notice there are two differences, but only one conflict. The | |
| first difference is not marked in red. That's because this line 3 <b>was | |
| not changed since the P1 tag</b>. If we had allowed the start tag of the | |
| merge dialog to remain at <b>Root_p1test</b>, this would have been | |
| interpreted as a change and hence a conflict. If we had not had the | |
| conflict in the second change of line 5, this would have auto-merged | |
| successfully.</p> | |
| <p>Another point to note is that the reason there is even any | |
| difference at all in line 3 is that we are not rebasing in this | |
| scenario. This is why line 3 of the branch is not in sync with line3 of | |
| main, even though it line 3 hasn't been changed since Iteration 1. | |
| Rebasing is addressed in <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article2.html">Part 2</a> of this | |
| article.</p> | |
| <p>The following steps simply repeat the conflict resolution of | |
| Iteration 1. This is represented by yellow diamond labeled <b>M2</b> in | |
| the scenario diagram. They are recounted here briefly.</p> | |
| </li> | |
| <li>Edit line 5 of the local file to say, "This line changed by | |
| Paul and Wing in iter2." | |
| </li> | |
| <li>Right-click in the local file area and select <b>Save</b>. | |
| </li> | |
| <li>Right-click the <code>f4conflict.txt</code> entry in the <i>Synchronize</i> | |
| view and select <b>Mark as Merged</b>. | |
| </li> | |
| <li>Commit the merge with comment "Merged p1test branch from P1 to | |
| P2." | |
| </li> | |
| <li>Tag the result <b>WM2</b> as indicated in the <a | |
| href="#scenario">Scenario Diagram</a>.</li> | |
| </ol> | |
| <h2>Summary</h2> | |
| In this tutorial we illustrated the implementation steps for a simple | |
| branch and merge scenario. We then extended it with a merge-again | |
| scenario. We saw how tagging milestones and merge results assist with | |
| future merges. We also saw a subtle effect of using these milestone tags | |
| for a base point rather than simply falling back on the original branch | |
| point. | |
| <p>One consequence of the merge tactic chosen for this article is | |
| that the <b>p1test</b> branch was never refreshed with changes on the | |
| main branch. This may be fine in some circumstances. To keep the <b>p1test</b> | |
| branch synchronized with changes in the main, a rebase technique must be | |
| employed. This is the tactic discussed in <a href="http://www.eclipse.org/articles/article.php?file=Article-BranchingWithEclipseAndCVS/article2.html">Part | |
| 2</a> of this article.</p> | |
| <h2>An Alternative - Ongoing Merges</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 the scenario for 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. It 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>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> |