This is an old revision of the document! Table of ContentsWorking with branchesTo branch or not to branch? The decision whether to branch or not is not really something that follows a strict formula, but you should consider doing your work in a branch if it:
Of these, the only really critical and absolute rule is that you must always exercise all possible caution to try to avoid breaking trunk/, and if you ever anticipate committing half-working code, you should almost certainly do this in a branch. Moving existing code into a branchThe best practice is to think everything out before you begin, realize that you will need to work in a branch, create that branch, and do all your work in there from the beginning. In reality, it is very common for a developer to begin some project without thinking all of this through for one reason or another. Perhaps what was supposed to be simple has turned out to be much more complicated than expected. Maybe a quick hour of code to knock something out is going to turn into a week or more before all the unexpected problems can be sorted out. Sometimes, you will even begin working from and committing to trunk/ without realizing that your work really should have been done in a branch first, and someone will ask you to branch and complete your work there; merging it after whatever controversy is resolved to everyone's satisfaction. This is simple to deal with, if this every happens to you. Simply take a patch of your current working copy before you proceed with creating a branch and checking it out. svn diff > <patch_my_branch> Note: Replace <patch_my_branch> with a real filename of your choosing To avoid causing yourself problems down the line, now that you have taken this patch to use later, you should revert these changes from your working copy of trunk/ before continuing. patch -R -p0 < <patch_my_branch> You can double check that everything worked properly by running svn diff This should produce no output. Note This technique works very well if all of your modifications were to files that were already under version control. If you have already started adding new files, but have not yet put any of them under version control, they will not be included in your patch, and you will need to keep up with them and move them into your working copy of your new branch later on. Unfortunately, svn diff is of no help in this situation. Creating a new branchWhether you are beginning completely from scratch, or you are creating a branch out of existing work you began in trunk/, the next step in this process is to create the branch itself in the Subversion repository. Create a new branch by copying trunk/. For example, for a branch called <my_branch>, do the following (as a single one-line command): svn copy https://<user>@rosegarden.svn.sourceforge.net/svnroot/rosegarden/trunk/rosegarden \ https://<user>@rosegarden.svn.sourceforge.net/svnroot/rosegarden/branches/<my_branch> You can see what branches already exist (so as to get ideas for a new name, perhaps) using svn ls https://<user>@rosegarden.svn.sourceforge.net/svnroot/rosegarden/branches/ (Or you can browse the the online Subversion repository at http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/branches/) Note: Replace <user> with your SourceForge username and <my_branch> with your branch name. Checking out a branchsvn co <my_branch> The full command to checkout my_branch using username is: svn checkout https://<user>@rosegarden.svn.sourceforge.net/svnroot/rosegarden/branches/<my_branch> <my_branch> Note: Replace <user> with your SourceForge username and <my_branch> with your branch name. After the checkout completes, take note of the revision number for later, so you don't have to dig it back up when it comes time to merge. The last message from Subversion will tell you this piece of information, for example: Checked out revision 10745. Applying your patchIf you took a patch of the work you began in trunk/ then now is the time to apply that patch to your new working copy of your new branch. Simply use patch -p0 < <patch_my_branch> Note: Be sure not to use the -R option in the patch command this time. Replace <patch_my_branch> with the real filename you selected earlier. If you created any files that were not yet under version control, and were not included in that patch, now is the time to move them across into this directory. Now you are ready to commit the beginning of your new branch, and get to work in here! Committing changes to the branchWorking with branches is as easy as working with the trunk. Commit the changes from the root directory of the branch. cd <my_branch> svn commit -m "Text which describes the updates." Merging changes from a branch to trunkFor most branches, you want to keep the merge as simple as possible, and only do this once. Chris Cannam recommends ignoring trunk/ until you are ready to merge, and then doing the merge starting by taking a temporary working copy of trunk/ to get started: $ svn co https://rosegarden.svn.sourceforge.net:/svnroot/rosegarden/trunk/rosegarden \ tmp-working-copy Then change into tmp-working-copy/, and using the revision at which you branched (which you took note of earlier) and the name of your branch, do something like: $ cd tmp-working-copy $ svn merge -r<10208>:HEAD https://rosegarden.svn.sourceforge.net:/svnroot/rosegarden/branches/<my_branch> Note: Replace <my_branch> with your branch and and <10208> with revision number of the branch noted earlier. Resolve conflicts, build, test… Then run svn diff to make sure what you're about to commit looks sane. Then fire away with svn commit Merging changes from trunk to the branchIf you are going to be working on the branch for a long time, you may wish to reduce the number of conflicts you may eventually have to resolve by periodically merging from trunk/ into your branch, and then merging the branch back at the end of its life cycle. You may check the Last Changed revision of the branch with command svn info Let us suppose that the last changed svn version was 8114. Then you would like to merge all changes since svn version 8115. You may do it with command svn merge -r 8115:HEAD https://rosegarden.svn.sourceforge.net/svnroot/rosegarden/trunk/rosegarden If there are no conflicts, you may continue by committing the changes to the branch. svn commit -m "merge from trunk" Note that such a committing does not work if you had conflicts, therefore, resolve conflicts before committing changes. Resolving conflictsIn the case of a conflict, there will be 'C' in the place of the file which contained conflicts. C foo.c Such a file will be split into several parts. foo.c foo.c.r8115 foo.c.r8119 foo.c.working After you have resolved conflicts, remove the extra files and commit the changes. rm foo.c.* svn commit -m "merge from trunk" Closing a branchWhen a branch is finished with, we usually either delete it if it was very short-lived and uninteresting, svn rm https://<user>@rosegarden.svn.sourceforge.net/svnroot/rosegarden/branches/uninteresting or else move it to the branches/obsolete directory on the Subversion server. If in doubt, do the latter: svn mv https://<user>@rosegarden.svn.sourceforge.net/svnroot/rosegarden/branches/my_branch \ https://<user>@rosegarden.svn.sourceforge.net/svnroot/rosegarden/branches/obsolete/ |