version control: a quick tutorial

About how it's set up:
I set up version control with Nell over the past few days to manage our files and revisions since several of us will be working on this project and trying to synchronize versions is generally a mess. Additionally, it will track changes for us, which proves to be invaluable on any large project.

I chose Subversion for our version control because I'm familiar with it and it's well-respected. Since we're using a Windows Server, I chose svn1click for easy setup and start up. It does most configuration for you through a Windows installer and goes ahead and starts the Windows service so you can access it.

I modified permissions to allow for all of us to access it through username and password, and to disallow anyone else from accessing it. Here's a little guide on setting a few of those things up, for future reference. It's super easy.

About how you should use it:
To access the repository, you need to download a svn client. I (and a lot of people) use TortoiseSVN. It integrates right into your right-click menu, making the repository easy to access. Go ahead and download and install it.

To set up your repository for the first time, make a folder where you'd like to keep your project. Open the folder, then right-click on the inside of it. You should see an option for SVN Checkout. Click it.

You'll get a dialogue box. Fill it out with the url of the repository, just prefixed with "svn://". In our case, that's svn://vegroup.cs.clemson.edu. The second folder should be the folder you just right-clicked in. The other settings are fine as-is.

 

After you click "Ok", you'll be asked for username and password. Ask me, and I'll tell you what yours is--it's different from your other passwords! After you authenticate, you'll get a progress dialogue box, and then if you look in your folder, you'll see stuff has been put there. The green check beside the folder means it's under version control. 

If you open up that folder, you'll see three others: branches, tags, and trunk. For now, we won't be touching "Branches" or "Tags", only "Trunk". Trunk is where all your work should stay, for the most part.

I'll step you through four processes right now: adding a file, modifying a file, updating your project, and restoring to an older revision.

Adding a file

 Open up the trunk folder. Make a file (any file will do for now). I'm going to make a text file and type some random gibberish in it. Now, let's say I want to add this to the project. Right-click in the folder, then choose SVN Commit.

When you click, a dialogue box will come up. In the top text box, write a comment that describes what you're adding. Comments help your team understand what you're doing, and find revisions when they  need to. The bottom pane is a list of files that you've changed. You can see that beside my new text file it say "non-versioned", meaning I've never uploaded it before. I am going to check that box so that it is uploaded.

I enter my login information and click okay, and now my file is under version control! Yay!

Changing a file
To change a file and its contents in the repository, just open up the file, do what you need to in it, then follow the same process as above.  Choose SVN Commit, then follow through the dialogue boxes. Your change is made!

Updating your project
Let's say that someone else was working on the project and added or changed some files too. It's good practice to make sure your files are up to date before you start working on them. So, before you sit down to modify any piece of the project, right-click and choose SVN Update. After clicking through a few dialogue boxes, your project will be brought up to date with whatever's on the server.

If you think it through a little, it's easy to see that this can cause some problems. What if you and someone else were changing a file at the same time? SVN handles this nicely. Instead of just overwriting your file when you update, it will show you that the files have a conflict and give you options on how to merge them. That's for learning about another day, though. Another thing you want to think about is that other people are using the code you check in. So, try not to check in anything that is broken, or else, other people will try to use it and be frustrated. Only check in once you have useful code. There are ways to get around this (like creating branches) but again, I'm not covering that right now.

Going back a revision
Let's say that I made a change in my code that turned out to make things go wrong, or that I realized I liked an old version of something better. SVN keeps track of all revisions so that you can go back to old versions.

To do this, right-click on the file you want to shift back. Then go to TortoiseSVN>Show Log.

You'll get a nice little list of all the revisions that have happened, along with the comments (this is why comments are important!!).

Then, you have bunches of options. "Compare with local copy" will show you the changes since that revision. "Save Revision to" will let you save that revision to another file. Open/open with will, well, let you open it. You can also pick "Revert changes from this revision" to make the changes from that revision go away, or "Update item to revision" will change your local copy to that revision.

Okay, there's a bit to get you started! You can do a lot more complicated things with SVN. Read about it yourself, or I'm sure I'll be posting more detailed steps for common tasks later.