When to create a branch
Create a branch when:
- You want to have a stable environment to work on a major feature without interference from other development.
- You don't want to worry about breaking something for others.
- You want to prepare for a release and want to stabilize the software.
Creating a branch
Use svn copy to create the branch in the branches directory:
svn copy -m "Create branch1 branch." svn://svn.reactos.org/reactos/trunk svn://svn.reactos.org/reactos/branches/branch1
Keeping the branch in sync with trunk
If the branch is under development for a long period of time, it is best to keep it in sync with the trunk branch in order to not have the two branches drift too far apart. Do this by merging changes from the trunk to the branch once in a while (say every two-three weeks). Use svn merge to achieve this, but first you need to figure out which revision to merge from. For your first merge to the branch, you need to use the revision at which the branch was created. Use svn log to find this information.
If you use TortoiseSVN you should read the Subversion/Merging with TortoiseSVN guide.
svn log --stop-on-copy svn://svn.reactos.org/reactos/branches/branch1
The bottom log entry shows the revision at which the branch was created:
r12735 | chorns | 2005-01-02 21:12:17 +0100 (sun, 02 jan 2005) | 1 line
Create branch1 branch.
Run svn info on your working copy to know the current revision. Remember to run svn up before doing this.
Path: branch_working_copy URL: svn://svn.reactos.org/reactos/branches/branch1 Repository UUID: e2f519d9-20a2-bc46-8705-e3bf7245ce19 Revision: 15132
Now you can merge the changes made to trunk since the branch was created (or since the last merge) using svn merge:
svn merge -r 12735:15132 svn://svn.reactos.org/reactos/trunk branch_working_copy
There may be merge conflicts. Resolve them, run svn resolved on the files or properties, test, and you are ready to commit the merged changes. It is very important that you write the range of revisions that was merged in the commit log message, since you will need to remember it for when you need to merge changes from trunk next time.
svn ci -m "Merged 12735:15132 from trunk" branch_working_copy
Next time you need to sync the branch with trunk, use svn log to find the commit message for the last sync, and use that as the first revision in the range of revisions to merge.
N.B. You don't have to keep the whole branch in sync if you are only working on a part of the branch. In that case, just keep the parts you work on in sync.
Merging the changes to the branch back to trunk
When you are satisfied with the results on the branch, you probably want to merge it back to the trunk branch. Once again, you use svn merge to achieve this.
Checkout a working copy of the trunk which we will merge the changes into. Once again, use svn log to find the revision at which the branch was created (or the revision of the last merge to trunk).
svn merge -r 12735:15132 svn://svn.reactos.org/reactos/branches/branch1 branch_working_copy
Resolve merge conflicts, test, and finally commit it. Again, write the revision range in the commit log message for use in the next merge to trunk (if any).
svn ci -m "Merged 12735:15132 from branch1" trunk_working_copy
These tips may be useful to you when you work with branches:
- If you are completely rewriting a file on a branch, then delete and recreate it on the branch instead of just changing it. Doing so will avoid merge conflicts when merging the branch to trunk. You won't get notified of conflicts when doing this so use it carefully to avoid overwriting important data during a merge.