http://www.eclipse.org/articles/acticle-cvs-branching/eclipse_branch.html
Branching with eclipse and cvs
Summary
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 .
By Paul Glezen, IBM JULY 3, 2003
IntroductionIn 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 IBM® redbook, WebSphere® Studio Application Developer Programming Guide, contains a section entitled Streams in CVS. 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.
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.SetupThe 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.
Create a New Simple Project Called Brtest. Add A New File Called F1.txt. Add The Following Contents.
This File Will Only Be Edited
By Paul
This Line Will Be Changed Later.
The Rest of this File Will
Remain the same.
Add A File Called F2.txt with The Following Contents.
This File Will Only Be Edited
By wing.
This Line Will Be Changed Later.
The Rest of this File Will
Remain The Same. Add A File Called F3triVial.txt with The Following Contents.
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. Add A File Called F4conflict.txt with The Following Contents.
This file will be edited by
Paul and wing.
This Line Will Be Changed By
Both Paul and Wing.
The Rest of this File Will
. Remain the same After adding the above files, your workspace should look something like the screen shot below Add the project to CVS Right-click on the project folder and select Team -...> Share Project Select CVS as the project type and .. click Next Choose a suitable respository and click Next This creates an empty CVS project called brtest We still need to add the files to source control and commit them In the Synchronize -.. Outgoing Mode view, right-click the brtest folder and select Add to Version Control. Once again, right-click on the brtest folder and select Commit .... Provide an initial comment such as "Initial Version." 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:. Workbench User's Guide -> Tasks -> Working in the team environment -> Checking out a project from A cvs repository.
Branch Methodwhen Branching Off A Development Stream, IT IS OFTEN Advisable To Rebase Before Merging The Branch Back to The Main Branch. T
rebase 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 ..............................
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.creating The Branchat this Point, Paul and Wing Have The Same Version of All Files. It is now time forpaul to create an independent branch on which to work.
Right-click on the brtest project and select Team -.> Branch .... A Create Branch dialog box is displayed Enter a branch name like "p1test." Leave the check box checked for Start working in the branch Notice that a. version name is automatically filled in for you called "Root_p1test." you may choose a different name (so long as it does not 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 OK. you should be able to see the result of your branch in two ways. By right-clicking the project and selecting Properties and then CVS, you should see the p1test in the Tag Field. If you have the cvs label decorations enabled, you'll see the branch tag in the navigator view (see below).
To enable CVS label decorations, go to Window -> Preferences and navigate to Workbench -> Label Decorations Check the CVS box Paul will modify the first file using the p1test branch Open the editor for f1.txt Change line 4.... "this line will be changing later" to "this line HAS been change." Save the change. Open the Editor for f3triVial.txt. Change Line 4 and 5 from "this line will be change by Paul Only" to "this Line Has Been Changed by Paul. "Save The Change. Open the Editor for F4conflict.txt. Change Lines 4 and 5 from" this line will be change by Both Paul and wing "to" this line haas been change by paul. "Save the change right-click on the brtest project and select Team -...> Synchronize with Repository In the Outgoing Mode view, right-click the brtest project folder and select commit 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. Now i t 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 does not need to perform a branch change. As Wing, begin editing f2.txt. Change "This line will be changed later "to" This line has been changed. "Save the change. Edit f3trivial.txt in Wing's workspace. Change lines 9 and 10 from" This line will be changed by Wing only "to" This line has been changed "Save the change. Edit f4conflict.txt in wing's workspace. Change Lines 4 and 5 from" this line will be change by Paul and wing "to" this line was change by wing. "
Save the change. Commit Wing's changes. Notice her revisions numbers are all two digits. That's because her new revisions occur on the main branch.The MergeNow it is time for Paul to merge his changes into the main branch where Wing's work resides.
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 brtest project in the Navigator view and select Replace with -.> Branch or Version .... You should see a branch selection similar to the one below The p1test branch is the one Paul was working on to switch back to the main branch, select HEAD. . This is the CVS name for the main branch. Make sure Recurse into sub-folders is checked so that all the files in the project are replaced with the main branch contents. Then click OK. 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 HEAD branch (or main) Right-click on the brtest project and select Team -...> Merge ... Displays a panel allowing you to choise a "Start Point." For this ex ample, the only start point available is Root_p1test, the one Paul made by creating the branch. Select it and click Next. Next we specify from which branch to pull the changes. Expand the Branches node and select p1test. Click Finish. This is where The Fun Begins. You Will Be Presened with The Merge Editor '
s Structure Compare view with the following merge results. f1.txt was not changed by Wing, so it will come in without a problem. But f3trivial.txt and f4conflict.txt were each modified by both Paul and Wing. These will require special attention during the merge. Right-click on the brtest folder and select Update from Repository. This action only operates on non-conflicting resources (those with no red marks) in the Structure Compare view. in our example, it pulls in the changes to f1 .txt. This should leave your Structure Compare view with only two conflicts. Right-click f3trivial.txt in the Structure Compare view and select Merge changes into Local Copy. Since f3trivial.txt was a trivial merge, the merge editor automatically copies the changes From The P1test Branch Into Our Local Copy of The Main Branch. Inspection of F3triVial.txt Will Reveal The Changes Made by Both Paul and Wing.
Note We Haven't Merged Into Main Yet. That Doesn't Happen Until Wess. For now We've Just Merged Into our local copy; hence the name of the menu option. # F3triVial. txt, in the resource view that is not under source control. It contains a copy of the pre-merge contents for restoration purposes. Double-click f4conflict.txt to open the Structure Compare view of the merge tool. The left side of the Text Compare panel is the local copy of the main branch contents. The left side is the brtest 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. We can't resolve this conflict by simply sale one side or the teacher. for this case Same text window and select save. Since We since finished manually merging f4conflict.txt, WE No Longer Nee d to retain it in the Structure Compare view. Right-click f4conflict.txt in the Structure Compare view and select Remove From View. This only removes it from the view, not from the project. At this point, the merged copy only exists in . our workspace We still need to save it to the CVS respository Select the brtets project in the Navigator view and select Team -...> Synchronize with Repository These changes should not present any conflicts Right-click on the brtest folder in the Synchronize View and select team be "merge prtest branch to main."
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 brtest project in the Navigator view and select Team -...> Tag as version ... from its context menu Enter the name "p12merge" for the tag name Click Finish.SummaryIn 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
Merge Changes 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
Merge Changes with Local Copy ON
F4conflict.txt.
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 Navigator View and SELECTING TEAM -> Show in Resource History. The Resource History for f4conflict.txt is show Below.
We can barely see the Root_p1test 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 THE LABEL "P12MERGE."
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.AppendixIn 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
Merge Changes INTO LOCAL COPY 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.
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.
It is recommended that incremental compilation be disabled when using this method on source code files This is done from the Windows -.> Preferences dialog by selecting Workbench on the left side and unchecking Perform build automatically on resource modification.
Right-click f4conflict.txt and select Merge changes into Local Copy. 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. In the figure above, the non-trivial merge marker appears on f4conflict.txt. Note the presence of two additional files not under source control.. # f3trivial.txt and. # f4conflict.txt files contain copies of the pre-merge contents for restoration purposes. We now want to resolve the merge conflict for f4conflict.txt indicated in the resource view above. Open the f4conflict.txt in an editor. 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 ">>> f4conflict.txt" and "<< 1.1.4.1", inclusive, to contact "this line haas been change by Paul and wing. NOTICE that saving the result will change the merge conflict marker. The assumption is that the save action resolves the conflict.ReferencesListed below are some references to which one can refer in addition to the Eclipse documentation.
