Basics

SVN is less tree-structured than CVS; more things live at the top level. For example, instead of being under a software/zope folder structure, all the Zope products are top-level, checkoutable entities in their own right. Other "modules" that were formerly under several levels of structure are also at the top level now, like bibtexml, roadmap, xml, etc. To see what the top-level modules, are, log in to barracks and type svn ls svn+ssh://software/.

Instead of using deeply nested folders to group things hierarchically, our svn install will use bundles. A bundle is a sort of label that allows you to check out multiple chunks of the svn repository at once. For example, there'll be a Rhaptos bundle that includes all our Rhaptos products, analogous to the big RISA folder we had in CVS for a while. There'll be another bundle that includes the Plone components (some of which will come directly from Plone's svn system instead of ours!). There should also eventually be a bundle that includes everything you need to install and run a Rhaptos system. In practice, regular developers may not use bundles much; we'll just check out the specific products we care about and leave it at that.

Setting yourself up for svn

First, make sure you don't have any important uncommitted modifications in your CVS working directories. If you have a few, move them aside and you can plop them on top of your svn checkout later; if they're extensive, go see Ross. Then create a directory for your svn checkouts and change into it (I called mine...svn).

If you wanted to check out abso-bloomin-utely everything (DON'T ACTUALLY DO THIS), you would type svn checkout svn+ssh://software/ The reason you don't want to do this has to do with branches, covered later. Basically, if you really checked everything out of the top level of our repository, you'd get over a gig of data, including the entire revision history of every file we've got! Instead, you want to specify that you want the latest files, or the "trunk".

Normally you'll only want a few of what cvs called "modules", like for example the "cnxml" directory, or a couple of products, like RhaptosRepository or CNXContent. So here's the actual syntax you want to use:

svn checkout svn+ssh://software/cnxml/trunk cnxml

svn checkout svn+ssh://software/RisaContent/trunk RisaContent

That command, issued inside your directory, will create a working folder called "cnxml" or "RisaContent", respectively. It will then check out the "trunk" (basically the HEAD) of the cnxml files into it.

Once you're in a working directory, you don't have to use the svn+ssh://software part; that's the full path to the stuff in svn, and like in cvs, once you're in a working directory it knows where to go to find stuff. The full path is equivalent to the -d option to the basic cvs command.

Basic commands

As far as I've noticed, the really basic commands remain really basic. There's update, commit, status, and diff. The output of status is quite different, but I'm sure it has options that will get us to the same basic info we had in cvs. To get all the commands, do an svn help.

The biggest win so far for me in subversion is the ability to move/rename stuff; there are actual svn commands for that, so you can move things in a way svn is aware of, and not lose their history.

So, what's this trunk stuff, you ask? Play some with the svn ls command, which lets you browse the svn repository without having to have stuff checked out at all:

svn ls svn+ssh://software/cnxml

This doesn't give you quite what you'd expect; it only lists "branches", "tags", and "trunk". Trunk is where the actual files are.

svn ls svn+ssh://software/cnxml/trunk

That's where you find the familiar files you were looking for, and that's why there's a "trunk" component in those checkout commands above.

To go deeper, tack further subdirectories on after the trunk component. The trunk part (and the branches and tags parts) only exist(s) right up under the top level. So to get further down in your explorations:

svn ls svn+ssh://software/cnxml/trunk/style

svn ls svn+ssh://software/RisaContent/trunk/skins/RisaContent

The "trunk" level doesn't show up in your actual checked-out copy; it's only there when you're referring to a path in svn.

Branches and tags, tranches and bags

There's no difference between branches and tags in svn; the only reason we have both is that cvs considered them different. Svn's version of the same concept is...kinda different from either one of the ones in cvs. Both branches and tags in svn are whole separate copies of the module in question, rather than bits of metadata attached to files and folders. Ross tells me they're "smart copies", which means they use space wisely and all, but from the ls and/or checkout perspective they look exactly like big redundant copies.

To work with a branch in svn, you check it out from a different place and to a different place. Instead of using "trunk" as an element in your svn path, you use "branches". Use these commands to compare and contrast what you get with "trunk" and "branches" in !RisaContent:

svn ls svn+ssh://software/RisaContent/trunk

svn ls svn+ssh://software/RisaContent/branches

So, instead of checking out a given module "on" a branch, and having to use a status command later to see what branch it's on, you just check out a whole different copy of the module. There's no moving back and forth between branches and head within the same working copy, like you might have done in cvs with update -r ![tag name]; any working directory you have is locked down to one branch or another. Trunk is actually just another branch, and behaves just like one in this respect.

If you want to "move" to working on an existing branch, you can probably just do a checkout from the branch, and put it on top of your old working copy. But since we're given the option, I might do something like

svn checkout svn+ssh://software/RisaContent/branches/eip-enhance-branch RContent-eip

so I can keep the branched stuff separate, and remember that that particular working directory is on the eip branch.

More advanced stuff

I won't even get into merges and such, since I've been using subversion for all of a few hours myself, but the help is pretty easy to get to, if not always crystal-clear. Use svn help and/or svn help (command). The basic help command will also give you the shortcuts for the common commands, which I are very similar to cvs's (co, ci, up).