Subversion Tips and Tricks
Useful Resources
There's one resource you can't do without: "the SVN Book," also known as Version Control with Subversion. Fluid is currently using SVN version 1.4, so here's a link to the correct version:
Using SVN externals
Externals in Subversion can be used to pull resources in from another module or repository. We try not to use them extensively in the Fluid repository, but they can be useful when linking to our components code from the incubator or scratchpad.
In SVN, externals are managed by the svn:externals property. To edit them, you can use "svn propedit svn:externals ."
Taking our lead from how Sakai handles externals, you've probably noticed that they use a separate file called .externals. Editing it does nothing by itself. Here's how to use it:
1. Create a new plain text file in which you will place your externals. The contents of the file should be formatted like this:
fluid-components https://source.fluidproject.org/svn/fluid/components/trunk/src/webapp/fluid-components/
2. Use svn propset to push the values from your .externals file into the svn:externals property for the current directory.
svn propset -F .externals svn:externals .
Creating a branch
In Subversion, branching is a simple as making a copy of the trunk:
svn copy https://source.fluidproject.org/svn/fluid/components/trunk
https://source.fluidproject.org/svn/fluid/components/branches/FLUID-wxyz
Don't forget to file a JIRA ticket related to the work you intend to do in the branch, and make sure you name the branch after the JIRA issue. Whatever you do, make sure you're branching a current revision in the repository; that's why I always create branches using URLs. If you do branch a local working copy, double-check that you don't have any pending changes in it. Life will be much more complicated when you come back to merge the branch if you had pending changes in the local working copy.
Keeping your branch from getting crusty
As changes to continue to occur in trunk, you'll want to keep your branch up to date as much as possible. This helps to avoid bigger merging problems when it comes time to move the changes from your branch back into the trunk. Keep in mind that you'll want to be merging the changes that occurred in trunk from the point at which you branched until the current revision. Here are the steps:
1. Make sure you've got a totally clean, unmodified, and fully up to date version of your branch. svn status will tell you if there are any outstanding changes you need to deal with first.
2. Find out version at which you created your branch:
svn log --stop-on-copy
The stop-on-copy flag tells SVN to only show the log up to the point where any copies were made. Since you copied the trunk to create your branch, the earliest revision number listed here should be the revision at which you created the branch. Double check the log message to be sure, and then make note of this revision number (without the "r").
3. Find out what the latest revision number is. You can determine this by running svn update on a working copy of the trunk, or by taking a look at the web interface for the Fluid repository.
4. Merge the changes into your working copy:
cd <my-branch-working-copy>
svn merge -r <branch-creation-revision-number or revision-of-last-merge>:<latest-revision-number>
https://source.fluidproject.org/svn/fluid/components/trunk/ .
5. Test, test, test.
6. Do an svn st to double-check the changes that were made, and then commit the changes to your branch.
Merging your branch back into trunk
This is pretty much the exact same principle as above. Remember, when you're merging a branch, you're merging the changes you made in the branch, from its first revision until now, into trunk.
1. Check out fresh, unmodified copy of both your branch and trunk. Really, make sure they are fully up-to-date.
2. Make a note of the revision number at which the branch was made. It should be the first log entry when you run svn log like this:
svn log --stop-on-copy
3. Make note of the current head revision. Running svn update or checking the web interface will get you the goods.
4. Merge the changes made from your branch into trunk, like this:
cd <trunk>
svn merge -r <branch-creation-revision-number>:<latest-revision-number>
https://source.fluidproject.org/svn/fluid/components/branches/<MY_BRANCH> .
5. Test like crazy.
6. Double and triple check that all the changes are as expected, using svn status and svn diff
7. Commit.