SVN is confusing, or at least it can be for people who don’t know their way around the Terminal or aren’t exactly sure what SVN is. I was confused by it for a long time and I’m decently technologically inclined. (+1 spelling) This article is intended for those who are forced to use SVN against their will and I will be very explicit and redundant about what is happening and why.

SVN can be learned!
 
You too can learn to love it!
 

Some technical information first, I’m writing on a mac and I use SVN on a mac. If you ALSO are on a mac, you’ll need to have the latest Developer Tools installed. They’re not installed by default so if you haven’t done this already you should do that now. If you’ve lost the install CD that came with your computer you can grab it here for free (it’s a big HUGE download). You probably won’t use 90% of the stuff that it installs, but there’s some background stuff going on that you’ll need (SVN for example).
 

Check to see if SVN is installed, open Terminal (Applications > Utilities) and type “svn”.

If you see something similar, it worked! If not, sorry, try Google.

OKAY, install done. There are several graphical interfaces for SVN but I’ve found that none of them can really compare to the command line interface (someone will hate me for saying that). Even if you use a GUI for SVN, sometimes something will break and the program won’t be able to fix it.
 

First I’ll cover some Terminal basics to help you get around.
 

How to change directories (folders):

cd, which probably stands for “change directory” is how you’re going to get around. If you’re in the terminal, you’re using cd all the time.

This following commands will take you to the root (Macintosh HD), your home folder (/Users/yourname/), and up one folder, respectively.

Want to see what other folders/files are in the directory you’re in?

If you get lost you can use “pwd” which will return the current directory that you are in. (Print Working Directory)

Cluttered screen? Try this:

Okay, that should be enough to get you scooting around nicely. Let’s get into some SVN goodness! So first you’re probably going to want to “checkout” a copy of the repository (or repo as I will call it from now on). First cd into the directory where you’d like your local copy to be. I usually checkout to ~/myUserName/Sites/ because I’m usually working with websites, but you can put yours wherever you like. Then get the URL to the repo. You’ll probably get this from the IT guys or from someone sitting next to you. The following will checkout the repo “superImportantProject” which will put a folder called “superImportantProject” in whatever directory you’re currently in.

At this point, assuming you typed the url in correctly, you’ll see a bunch of text start to appear on your screen. If it’s going slow enough you can see each file that it’s downloading to your computer. Magic! You’ll know it’s done when you’ve been returned to the prompt. So you just downloaded a bunch of files to your computer, la-dee-dah. Now’s when you do your thing and jump into the folder, edit a bunch of copy, add some new images, delete some redundant files.

Great! All done for now, finished what you needed? Cool, now it’s time to CHECK IN YOUR CHANGES! First, before checking in your changes you want to see if anyone else has made changes to the repo while you’ve been working.

Hold your breath while it checks – with any luck no one has made any changes, or at least no changes that have to do with your files. If no changes have been made you’ll see something like this:

If changes have been made you’ll see something like:

The letters before each file tell you what is happening to that file. A for added, D for deleted, U for updated. If you, god forbid, see a C, that means conflict. If you see that, you’re fucked. Well…at least you are until you read the part where I talk about that. But that’s later!

Okay, so you didn’t see the dreaded C of conflict. On to the next step. Double check to see what files you’ve changed/added:

Now a list of all the files you changed, added and deleted will be displayed. Mine looks like this:

Woah, what’s all that crap mean? M means that you modified a file (most common). A ? means that file isn’t under version control (it’s not in entered into svn yet). The ! means that a file is missing.

Well let’s add those ? files into svn first because those are pretty important for my project.

Or you can string the files together (separated by a space) and add a bunch of files at the same time:

Now run ’svn status’ again:

Cool, we’ve got the A of added so those files are ready to go. Now about that missing file (!). Did you really mean to delete it? Does it need to be deleted? Is anyone going to miss this file? Think about that for a bit because if you delete that file out of the repository you’re deleting it for everyone else, too. Still want to get it out of there? Okay, but be careful with this one.

Almost too easy, right? ’svn status’ one more time before we commit just to make doubly sure.

Awesome, all the files we changed know what they’re doing now. It should be said at this time that it’s okay to leave files unadded and missing (? and !) but they will be ignored when you commit to the repository.

Time to commit:

The -m in there is an “option”. You’re telling the command ’svn commit’ to look for a message with your commit. The commit command won’t work without a message so you’ll always need to do that. The actual message can be as explicit or as vague as you like, just know that the message is logged and can be helpful later if you need to go back and find changes you had made in the past.

Hey, congrats! You know all the basics of svn to get you through the day!
 

This next bit holds some basic tricks to clear up any problems you might have as you flounder your way around svn.
 

Crap. I deleted a file that I didn’t mean to, how can I get it back?!
Well if you deleted the file locally and didn’t delete it with ’svn remove’ that’s easy! Just run ’svn update’ and you’ll grab any new files along with any you might be missing. If you deleted it with ’svn remove’ then WHAT THE HELL?! What were you thinking?! Fuck, just keep reading for now.

Crap. I’m getting the dreaded C of conflict.
Oh no! When this happens svn makes a bunch of crazy-ass files. Let’s just say your file was called “example.html” because I’m not feeling very creative right now. Now you’ve got:

If you were to take a look in the example.html file right now you’d potentially see a bunch of weird code that isn’t yours. The file that has all of your changes in it is now called “example.html.mine”. The other two files (r767 and r768) are the revision you were editing from (r767) and the latest revision that’s in the repository (r768). The easiest way out of this is to decide what version is the right one.

• Your co-worker has been working there for years and is way smarter than you, so just assume what they did it is right. Turn to page 768. Er, go with revision r768.
• Your co-worker is worthless which is why you were hired, your changes are right. Go with your copy (.mine).
• Both of you are idiots so let’s just start over and let the senior devs deal with it. Go with the old revision (.r767).

Whatever you decide, you’ve got to copy the file you want to go with over the original file then tell svn you’ve resolved the problem. My co-worker’s changes are usually right so I’ll just go with his:

The ‘cp’ command is used to copy file A to file B.

That should cover you for awhile… Once you get the hang of this stuff you shouldn’t have too much of a problem learning the rest yourself. If not, I’m still here!

trackback URL for this post: http://lab.joelgillman.com/archives/103_svn-for-newbies/trackback