In the third and final part to my SVN primer I will finish up with my day to day tasks and I will go over how to add SVN properties to your project. The first two parts can be found here: 1,  2.

More Terminology:

BASE – Refers to the most recent revision currently on your local workspace.

SVN Commands:

Comparing revisions – To see what changes have been made between two revisions a comparison can be run. The changes will be highlighted in gray, along with a box showing where in the older revision the change fits in. To compare revisions right click>compare with and then select the option that best suits your needs.

Merging – One of my least favorite of SVN commands, not because there is anything wrong with the merge feature (it's actually a great feature), but often when I run merges I have to deal with several conflicts, which I never find an enjoyable experience.  Anyways merging is a little trickier than you might think. Initially you might try merging the head of your branch (or whatever you are merging) with the head of your trunk, however this is incorrect. You actually need to merge the head of your branch with the revision of your trunk when you made the branch. This needs to be done because Subversion needs to know what actually has changed since the branch was made.

Add – If there is a file that is not under version control, but you would like it to be include this can be done by right clicking on the file team>add to version control

Ignore – On the flip side, if  you do not want a file to be under version control right clicking>team>add to svn:ignore

SVN properties – One really useful feature is svn properties. There are a wide assortment of svn properties that allow you to do things like add meta information to a file (author, revision number, last modified, etc.), include a tracking number and link to a bug tracking system, among many other options. The easiest way to setup properties using subclipse is through the “Show Properties” view. Right click on the SVNProject root folder and go to Team>Show Properties. To add a property right click any where in the spreadsheet looking area and select “add property.” Select the desired property and setup the property's value. To setup the ability to use a bug tracking through svn we will need the following three properties added:

Bugtraq:label - Displays a message next to the box where a developer would put the (comma separated) issue numbers.
Bugtraq:url – This is the url to your bug tracking system. The “%BUGID%” appends the tracking numbered entered to its location in the url.
Bugtraq:message - Displays a message in the history view. “%BUGID%” creates a link to the bug entered during the commit.

The end product, when you select a specific revision in the view history view in the bottom left you should get a message like “Tracker #s: 123” With "123" being a link tracker 123 in your bug tracking system. Eclipse has a built in browser, so when this link is clicked a browser window should open within Eclipse taking you to the issue.

This concludes my SVN primer. I hope anybody who reads this finds it useful. If you have any questions let me know. For more information on SVN you can check out these links:
http://markphip.blogspot.com/ - The blog run by the director of subversion engineering at Collbanet
http://svnbook.red-bean.com/en/1.5/index.html – A huge guide on how to use Subversion

Technorati Tags: Subversion, SVN

In part one I went over how to get SVN setup and configured on your system. In Part two I will get into the day to day activities of using SVN. In this part of my SVN primer I will cover; Checking out, committing, updating, synchronizing, branchings, and tagging. I will also go over some terminology to help make things a little more clear. I will be using subclipse as my SVN client in this part of the primer. I find using SVN from within an IDE to be more natural and including directions for both subclipse and tortoiseSVN to be confusing and there is very little difference between the two anyways.

Terminology:

Head Revision – Refers to the most recent revision in the repository.

Trunk – The main working directory of a project.

SVN Commands:

Checking out – To retrieve a project from the repository open up the “SVN Repositories” view and navigate to the project you wish to check out. Following with the example from part one it would be SVNProject>Trunk>SVNProject click finish when the next screen pops up. I find this method to be the easiest and quickest way to checkout a project.

Committing – When you have modified a file (or created a new file) you will need to “commit” it for the file to be included in version control. Subclipse keeps track of the files you have modified and when they are out of sync with the repository they display an icon next to that file stating so, subclipse shows a brown box with a white asterisk (new files are a question mark). To commit your file right click on the file(s) you wish to commit and go to team>commit . You will be presented with a pop up box, you here you will put a message of why you are committing a file, ALWAYS put a message. Messages will server as a quick reference when looking over a files history (explained below).

Updating – To get the latest file(s) from the repository you will need to run an update. To perform an update select the file/folder(s) you want to have updated and right click team>update to HEAD.

Conflicts – A conflict arises when you have a file that is out of sync with version control and you have edited line(s) of code that have been checked in since the last time you have run an update. Because SVN cannot itself determine which piece of code is correct, you must manually look at the code and determine which is correct. Here is an example of a conflict:

1.This is the change you made
2.This is the change that has been made in subversion since you last updated
3.This is several versions of the file that is in conflict
1.XXXX.java.mine is the file on your local machine
2.XXXX.java.r(lowest number) is the most recent file you retrieved from the repository
3.XXXX.java.r(highest number) is the newest file in the repository

In order to resolve a conflict you need to determine which change is correct. In this case I will keep my change, so I will delete the SVN markup (<<< .mine, ====, etc.) the change I do not like. So my file will like this:

You will also notice a weird little symbol that looks like a X with a square over it, this is the “conflict” symbol. You cannot commit a file to the repository that is in conflict. To remove the conflict you must delete the .java.mine, java.r(lowest number), etc. files. Once this is done you can commit your file to the repository. To resolve the conflict right click on the file and select Mark as Resolved, then select the action you wish to take. The "conflicts have been resolved option" uses the current file in your code view, "my file" will use the ".mine" file, incoming file will use the .r(highest number), base will use the .r(lowest number) file. (Thanks Mark!)

Branching – Most work on a SVN project is done in the “trunk” folder. There maybe times though when a change needs to be made to a project, but that change cannot affect the trunk, or a change need to be made, but it cannot affect code that will be going to production. In these scenarios a “branch” is crated. A branch is a copy of the current head revision of a file(s) that is placed in a separate folder (typically under “branches”). To create a branch right clicks on the file/folder you wish to branch and go to team>branch/tag>select your destination ({project name}/branches>name the new branch

Tagging – A tag is like a branch, however it represents snapshot of a project instead of a working directory. Typically a tag represents a project version or code that has been pushed to a production environment. When you attempt to commit a file to a tag a warning message is displayed stating a file is being committed to a tag. To create a tag team>branch/tag>select your destination ({project name}/tags>name the new tag.

REMINDER: When you branch or tag a project, the branch/tag is created off the Head revision of what is in the repository NOT what is stored locally on your computer.

View history - Subclipse allows you the the view the history of a file(s) stored in the SVN repository. The history view will show when the file has been modified (checked into SVN), the revision number, and the comments when the file was committed. To view the history of a file right click on it go to team>show history.

Reverting – Reverting allows you to retrieve a previous version of a file from the repository. Reverting is typically done to get rid of unwanted changes or for debugging reasons (i.e. a bug is known to exist in version X of a project). A neat thing SVN allows you to do is revert an entire project to a specific revision. When this is done all files are not the same revision number, but the version number they where at the time that revision was made. To perform a revert right click>team>update to revision>select the revision you wish to revert to.

This will conclude part two of the SVN primer. In part three I will go over a few more day to day task of using SVN. I will also go into a few advanced topics like setting up SVN properties which can be quite useful. Check back later this week for part three! If you have any questions please let me know.

Technorati Tags: Best practices, Subversion, SVN