2011-November: This document is now obsolete. Subversion is no longer in use. We are in the process of consolidating and re-organizing the website documentation. For now please refer to the in-progress website documentation.
As we've already announced earlier, we're planning to switch our version control system from CVS to Subversion. While CVS is working nice basically, it's much too limited to serve as a good foundation for a project of a size like ours.
The following document should give you an introduction on how to use Subversion with our repository - it will not provide you with many details, but with some pointers in case you want to know more about Subversion. The current version of Subversion is 1.1.3.
It will also not cover the installation of Subversion on BeOS - alongside this document, we've published a package that will take care of this for your convenience. To successfully use Subversion on BeOS with our provider of choice, BerliOS, you'll need an updated ssh client, a new pipe file system (developed by FranÃ§ois Revol), the flock_server (that provides a file locking service needed by several applications), and of course, a recent Subversion client. You have to thank Ingo Weinhold and David Reid for the availability of these ports for BeOS.
Setting up the local repository
The most important difference for you is that you don't want to check out the entire repository anymore: unlike CVS, Subversion would leave you with all tags and branches as separate files on your hard drive - which totals in about 1.4 GB of files at the moment. Instead, you will specifically ask for the "trunk" only - that's what you already know as the CVS root now. And in there, you may also not need to check out the build tools, as these are available separately, and ready to be installed, anyway.
Checking out the sources
If you want to do an anonymous checkout, you don't need SSH - this should already work with the Subversion release as published on BeBits. To get a copy of the current Haiku tree (and Haiku only), you would write something like this:
svn checkout http://svn.haiku-os.org/haiku/haiku/trunk [directory-name]
This will create the directory "trunk" in the current working directory and put everything from the repository under haiku/trunk into it. If you don't like the name "trunk" on your disk, you can specify the optional directory-name parameter.
You'll probably notice that "current" is gone - it's now called "haiku". Anyway, this should take a while, but give you a recent copy of our current sources. Note, before the actual switch, we'll be freezing CVS commits and then update the Subversion repository from the most recent one; what you currently get from BerliOS is quite outdated.
For a developer checkout, it's quite similar:
svn checkout svn+ssh://svn.haiku-os.org/srv/svn/repos/haiku/haiku/trunk
Don't be confused by the double password retrieval: that's obviously how it's meant to be (at least it's not a bug we claim credit for). It will only do that with the checkout command; update and all other commands needing access to the repository work as expected. But you may want to store your public SSH key at BerliOS's so that you don't ever have to type it in again.
Note, if your local user account is different from your login name at BerliOS, the SVN_SSH variable must be set a bit differently for things to work:
export SVN_SSH="ssh -l developername"
You can pass other options to ssh this way as well if you wish. Unlike CVS, if your local user name is identical to your developer name at BerliOS, you don't have to set the variable at all, though.
Keeping the sources up to date
This is an easy task, and is very similar to what you're used to from CVS:
Of course, this will also work in sub directories, in case you only want to update a certain piece of the tree. And just like with CVS, you don't have to specify the URL of the tree when you are issuing a command from inside a checked out tree.
Some Subversion specials
- Unlike CVS, Subversion does not need a network connection to show you the changes you made to your working copy - this will reduce the network usage to a minimum (the svn status and svn diff commands). This has a couple of other advantages as well, like the svn revert command which you can use to undo local changes.
- Subversion has a real rename feature - now you can move files (and directories) around without losing the file's history.
- If a conflict occurs during an update, Subversion doesn't let you commit files marked as conflicting. After you've resolved the conflict, you need to tell Subversion that the conflict is no longer an issue by calling svn resolved . You will also notice that Subversion helps you resolving the conflict by creating some files in your working copy that contain the originally checked out revision as well as the verbatim new revision of that file.
Tags and branches
In CVS, tags are just common names for a set of files with specified revisions; branches add some hidden dimension to concerned files. That makes it not so easy to see which files are actually tagged, respectively are contained by a branch (unless you just check the tag/branch out).
In Subversion, a tag is just a copy of the directories and files to be tagged, placed in a designated part of the repository. Branches are just the same, with the difference that while you usually leave tags alone once you have created them, in branches you still do editing. If you tag or branch from a branch, you guessed it, you just make a copy of the branch. All this copying sounds like a huge waste of storage, but in fact Subversion copies lazily; that is, no actual copy of a file's data is made until you start editing it.
Regarding the special place for tags and branches in the repository I mentioned, best have a look at the layout of our directory structure:
As we had in CVS we have two main modules, buildtools and haiku. Here only the structure of the latter is shown. Little surprise, the subdirectories branches and tags are the places for branches and tags respectively. vendor is the place for vendor branches. It has subdirectories for the components whose contents are managed as described in the Subversion Book. trunk has already been mentioned above; it is the main trunk of development.
The directories branches and tags deserve a closer look. Both are structured exactly the same, so only branches will be described more in detail; everything applies analogously for tags.
The subdirectory components is intended for branches that concern only one component of Haiku which could be distributed independently of the OS itself, too. As an (imaginary) example say ShowImage: Version 1.0 is out and development for 2.0 with new features is in full progress, but it has been decided to release a bug fix version. For this purpose the 1.0-fixes branch has been created. By the way, it would most certainly not be a copy of the whole Haiku tree, but only of the respective subdirectory (src/apps/showimage). If your component has headers and sources, which are stored in separate subtrees in the Haiku source tree (headers and src respectively), you don't need to copy the whole Haiku source tree either. You can create the branch directory by hand and copy only the concerned parts of the tree into it.
developer is the place for developer branches. Any developer who desires so can have a subdirectory. If you're paranoid and want to always commit your day's work even if it doesn't compile/work, this is the place. Or you have different computers you use for Haiku development and need a means to keep them in sync. Or you want to do experimental development. Just use this directory. Its inner structure is completely up to you.
A similar place, just for whole teams, is the team subdirectory. It shall mainly be used for experimental development in which more than one team member is participating. For the inner directory structure the team is responsible.
Into haiku go all branches of the complete OS once we start releasing versions.
Finally there is the directory old which contains all branches that had been created with CVS and were converted to Subversion branches. To save the work of understanding what each one was for and sorting them into the respective directories above, we just put them here. When you need one of them, just move it into the directory it belongs to. Each branch starts at the directory current, but contains only the files that were actually branched. You usually want to move only the innermost directory containing all files. For example:
$ svn mkdir -m "Directory for jam branches."
$ svn mv -m "Moved JAM2_4_VANILLA_FIXES branch to proper place."
$ svn rm -m "No longer needed."
This moves the branch JAM2_4_VANILLA_FIXES branch to its proper place, extracting only the relevant subdirectory. As you see we do this directly in the repository (only URLs are used), which is (despite the long command lines) the most convenient way for copying and moving directories (this includes creating tags and branches).
If you're a developer, you probably need to know a little more about how to use Subversion. Here are some links that you might want to have a look at: