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

In my first multi-part tutorial I will give an in-depth primer on how to use Subversion (SVN). Subversion is one of the mostly widely used version control systems in the software development industry. Subversion is based off of CVS and while I haven't personally used CVS I'd imagine the vast majority of what is in this primer can be transferred over fairly easily to CVS. So this primer should effectively prepare you for any version control system you will likely encounter. There are a couple other version control systems out there, but these are the two major players.

The primer will be broken down into three parts; part one will focus on setting up a SVN server, installing the SVN clients and creating a new project. Part two will go over most of the day to day functions of using SVN. In part three I will go over a few more day to day SVN functions as well as go into a few advanced subjects like setting up properties, which can be very useful. This primer will be used as platform for some exciting future projects I will be doing on this site. If you do not yet know how to use SVN I would suggest reading up on this primer as it will be quite useful both for this site and your career.

Setting up the server

A natural starting point for this primer would be to get a SVN server setup on your system. While there are several options out there, the one I am most familiar with is VisualSVN. Click on the link and download VisualSVN. Once the file has finished downloading follow these steps:
1. Select install VisualSVN and management console
2. Uncheck use secure connection, port can be set to whatever you want, but I will be using the default in my primer (443), same goes for the repository location.
3. Install

Once the installation is complete the management console should automatically start. We now need to configure the SVN server:
1. Select create a new repository
2. Give your repository a name, I gave mine SVNTest, leave “Create default structure” unchecked
3. Next create a new user, my user name is ninjaneer with the username as the password.
4. On the left hand side of the screen, expand repositories, right click on SVNTest and create a new project called “SVNProject”

The clients

In order to effectively use SVN we will need to use a client. I will be actually covering two SVN clients; TortoiseSVN and Subclipse.

Go here to download TortiseSVN. Choose either the 32-bit or 64-bit flavor. This is a very standard install, just accept all the defaults and hit install.

Installing Subclipse is a little different as it is an Eclipse plugin, but luckily Eclipse has a sweet plugin installer to handle most of this for us. (If you haven't used it before here is a tutorial on how to use Eclipse's built in plugin install feature.) Here is the download site for subclipse: http://subclipse.tigris.org/update_1.6.x. Select “Core SVNKit Library” and “Subclipse” and continue with the plugin install.

Adding a project to SVN

In Eclipse we are going to create a new project. I will name the project “SVNProject” and I will accept the defaults. To upload a project to a SVN repository right click on the project folder>Team>Share Project>SVN. You will need to enter the url of your SVN repository; open up the VisualSVN management console and look for “Server URL is: http://xxxxx:443/svn/.” Copy the url and paste it into the dialogue box in Eclipse. BEFORE YOU CLICK NEXT, type in the repository name, in this example it is SVNTest, so your repository url should look similar to this http://xxxxx:443/svn/SVNTest. On the next page select “use specified folder name” then click the select button, select SVNProject>trunk. For organizational purposes it is best to give each project in the repository its own; trunk, branch, tag hierarchy, otherwise it can become very difficult to manage multiple projects.

This will conclude the first part of the SVN primer. In part two I will go over more of the day to day tasks of using SVN; checking out a project, committing, updating, resolving conflicts, synchronizing, branching, tagging, and reverting as well as some come terms. Check back later this week for part two. If you have any questions or comments please let me know.

Update:

Part two has been posted, check it out

Technorati Tags: Subversion, SVN