Getting Started with Subversion on Dreamhost

Since about January, I've been using Dreamhost as cheap, offsite Subversion repository hosting. It's worked well for me over that timeframe and I've got documents, lots of my software settings and configurations, web projects and more under version control.

Several people have asked me for a bit more explanation of how to actually get started with Subversion on the Dreamhost accounts.

You need:

• A Dreamhost account. If you don't have one, they're as low as $7.95/month when you prepay. When you sign up, if you use the code GLASSTOOBIG, you'll have your setup fees waived and I get a bit of cash to help out here.
• A copy of TortoiseSVN. I often use the commandline tools, but TortoiseSVN is what a LOT of people tend to use, so that's what I'm using to explain this.
• A Windows machine. Needed for ToirtoiseSVN to work.

In the Dreamhost control panel, the Subversion tools are under "Goodies", then "Subversion". We need a repository to put our stuff in. While we've all got differences, we all have documents, so that's the first repository that I recommend people build.

I set the project name to "J Wynia Docs" and the project ID to "jwyniaDocs". The project ID gets used as the URL of the repository, added on to whatever domain you are using for Subversion.

The sample usernames and passwords show you how to set up users. One user goes on each line and the username and password are separated by a space. The "Private" or "Public" switch is there if you want to add read-only access for the public to your repository. In either case, the users you create are always going to have both read and write access, making the public flag all about public access. It's mostly useful if you're running an open source project, so people can check out the latest build while still shielding the codebase from some random stranger from making changes.

Once you click the button to create, it usually takes a few minutes (though it's never taken the 10 they say) before it's ready. You can check that it's created if you get the "Revision 0" page when you click the http:// URL to the repository after being prompted for your credentials.

That URL is important because it's used as the basis for all of the paths to the files in your repository.

Once you've got TortoiseSVN installed, create an empty directory to be used as your working directory. While you certainly *can* import an existing tree into a repository, it works better with the commandline tools and isn't the method I'd recommend if this is your first time around the block. For your first repository, you should start out with an empty working directory, then add a copy of the files you want to add, commit them and then you can either keep the new working directory or you can delete both the original and the working directory and check out the project to the final place you want to work with the files.

Anyway, right-click in the empty working directory and do a "SVN Checkout". Use the URL you have for your repository and include the trailing "/". This is important later on, particularly if you want to check out just a portion of the repository. If you check out a URL like:

http://www.example.com/jwyniaDocs/trunk

into a directory, it will create a "trunk" directory, where if you check out

http://www.example.com/jwyniaDocs/trunk/

it will just check out the contents of that directory.

At any rate, you can just leave the rest of the stuff as is and let it do the checkout. Depending on your Windows Explorer settings, you may see the ".svn" directory, which is hidden. That directory has all of the information Subversion uses to keep track of which files change. You'll also start seeing green check mark for files and directories that are versioned and red indicators for those that are different than the latest version in the repository.

You'll note that the URL examples I gave above include a "trunk" directory. That's a convention you'll see a lot. Most versioning systems talk in "tree" terms with trunks and branches. This is usually implemented such that you create a branch for releases like your 1.0 or 2.0 versions, which you can then maintain separately from your ongoing development.

As a result, I always create a "trunk" directory and a "branches" directory at the root of my repositories and do most of my work in the "trunk". If you're going to do that as well, now's the time.

Then, copy the directories and files you want into the "trunk" directory (or the root if you forgo the trunk solution).

Now, your repository still doesn't know anything about the files. If you were using the commandline SVN client, you'd add them and then commit them. With TortoiseSVN, however, you can do both in one gesture.

Right click the empty space in the root of your working directory and you should see a slightly different TortoiseSVN menu than before. This is the "normal" working menu for it. Choose "Commit" and you'll get a dialog containing all off the differences between your working copy and the repository.

You'll notice that all of the "new" files are unchecked. This default ensures you don't accidentally commit things like temp files to your repository. However, for your initial commit, you probably DO want all of the files added, so you can use the handy "Select All" checkbox and it will add and commit all of those files to your repository.

It's a good idea to get used to adding comments on *every* commit. Even a quick note like "Initial commit" or "Basic HTML layout changes" can really help you out in the future when you try to figure out what changed in a file. Also, if you get used to not adding comments, you will eventually end up on a team where they're mandatory and you'll have a really difficult time.

I always check those initial commits via the web, which you probably still have open in a browser. You should see the "Revision 1" version and all of your files added.

From there, your daily workflow is:

1. Update to get any changes someone else (or you on another computer) might have committed.
2. Make and test your changes.
3. Commit your changes.
4. Repeat.

I'm an advocate of frequently updating your working copy. If you update regularly, you will avoid many of the situations where files are in conflict and you have to merge them.

At any rate, that's really all there is to it. You can create lots of separate repositories for different purposes. That's what I'd actually recommend because if you create one huge repository for all of your documents and all of your projects, if you ever try to check out the trunk, you'll pretty much have to head out to lunch while you wait for the checkout.

And, one last thing to note is that if you've got a transparent proxy between you and Dreamhost, it might freak out because SVN uses some extended HTTP headers to do its magic. I don't have a great solution to it because in my case, I was able to just shut the proxy off, but it's worth knowing about in case you run into the errors.