Subversion for the Lazy

I've been asked about subversion enough times to justify writing this quick and dirty article to save me future time. Read this guide if you absolutely need to get subversion working ASAP. Otherwise I highly recommend going through the svn book for more background information and advanced usage.

You will NOT be able to do anything right in subversion unless you understand WHY it exists. Subversion might be a pain in the ass, but that wasn't why it was created. Subversion is version control software that is supposed to help programmers organize their code. If you use it correctly, it'll fix all of the following problems:

• taking notes about the changes you were working on.
• going backwards in time to an older non-broken copy of a file.
• merging changes from multiple programmers on the same file.

This all starts with a subversion repository. Think of the repo as the original copy of your files. Instead of making changes on the original copy, you checkout a working copy and make changes to that. When you're satisfied with the changes you made in your working copy, you commit the changes back to the repository. Here is the absolute simplest case of using svn:

svn checkout svn+ssh://address.to.subversion/repository myworkingcopy

The 'checkout' command makes a copy of the repository and puts it into a folder named myworkingcopy.

Edit any of the files in your working copy. These changes will only be in your working copy until you commit them back to the repository. This means that if you make changes, and another person does a fresh checkout, they will not see your changes. If you decide to create any new files in the working copy, you need to let svn know with the 'svn add' command.

svn add new_file1.txt new_file2.java new_file3.avi

You can add any number of arbitrary new files.

Before you commit, you want to double check the changes you made. First type:

svn status

This lets you know what's being committed. 'M' means modified, 'A' means added, and '?' means it's a new file that hasn't been added. Read the last section for adding.

When you're happy with the files to be committed, type

svn commit

This will bring up your editor to type a note about what the changes in this commit are. If it says that no editor is set, google how to set EDITOR in bash. After the commit succeeds, anyone else who does a fresh checkout or an 'svn update' will get the changes you just committed.

If multiple programmers are using the same repository, then at some point you'll have to pull changes from other programmers. Instead of doing a fresh checkout every time, simply run

svn update

to bring in all the changes from the remote repository. It's a good idea to get in the habit of updating before you make your changes because otherwise you'll have to do unnecessary merging. Read about merging in the svn redbook.

To summarize:

svn checkout http://svn.somehost.com/path/to/repository my_own_copy
cd my_own_copy
(edit the files in my_own_copy)
svn add my_own_copy/new_file1.txt
svn status
svn commit

If svn ever says, '.' is not a working directory, then it means you are not currently in a working copy. The working copy is what you named the folder when you originally checked it out. See section about 'checking out'.

Never mix and match folders from different working copies. If you want to use mv, or cp, or copies files in and out of the working folder, read about 'svn copy' and 'svn move'.

If you try to add a folder, and it says it's already been added, then you probably meant to add the files within the folder. Simply do a 'svn add -R folder_name' to do a recursive add of all files in the folder.

All subversion commands start with 'svn'. To get a list of all commands, type 'svn help'. To get help on a command foo, do 'svn help foo'.

If you're on a Mac and you suck at Terminal, then go get svnX. If you're on windows, get Tortoise SVN.

This guide is for lazy people who won't spend 20 minutes to read and understand the subversion guide. I guarantee you'll save hours and hours of headache if you just take the time to learn it properly. This is the bare minimum to get started, and if you still have questions after this, go and read the svn red book. Learn about merging, learn about diff's, and learn how version control works. You'll not only help yourself in the long run, but you'll save the people you work with lots of time too.