Wrestling with Subversion

SVN (Subversion) is pretty well documented (see eg here) but they seem to tell you a whole lot of things you don't want or need to know, but don't tell you some vital things you do need to know. I finally succeeded in getting my repository into the form I wanted, but I ended up having to reimport whole directory trees several times, which, since SVN never forgets anything, means a lot of wasted disk space on the server.

Among the facts which the SVN doco doesn't really make clear:

You can use 'svn mkdir' to create directories in your repository, as well as your working copy ('copy' and 'delete' at least also work on the repository);
You can check out subsets of the repository (i.e. a tree of all subdirectories below a particular branch point in the repository);
The 'working copy' of these subdirectories 'remembers' where in the repository it belongs, so within that WC you can do 'svn commit' without specifying the path, and SVN will remember where the files belong in the repository. This is most useful if you have more than one copy of your code: a development and a release version for example. In this case, if you have edited a module which belongs to both versions, you can commit the changes without needing to worry that the file will go to the wrong version in the repository. It will go to the version from where you last checked out your WC.

I'm going to describe now what I should have done to set up my repository in the form I wanted it, supposing I had known from the beginning what I know now. I don't guarantee all these steps (such as the directory twiddling I did) are necessary, but they are a whole lot more streamlined than the messy procedure I actually performed.

Suppose your nice sysadmin has set up the repository for you, and it is located at

	http://servername/svn/username

Suppose you have a bunch of code on your computer in a subdirectory called

	~/python/src

You'd like to bring the actual python modules, i.e. files with names which follow the pattern *.py, under version control, but there is a bunch of other files in there (*.pyc, *~) which you don't want to version.

The first task is to sort out the repository structure. I decided I wanted the standard setup, so I did

	svn mkdir http://servername/svn/username/python -m "Setting up repo."
	svn mkdir http://servername/svn/username/python/trunk -m "Setting up repo."
	svn mkdir http://servername/svn/username/python/branches -m "Setting up repo."
	svn mkdir http://servername/svn/username/python/tags -m "Setting up repo."

Next, one has to make sure one imports into the repository only those files which one wants to version. Perhaps one can import selectively, but I chose rather to set up a temporary directory containing only those files I wanted to version, namely the python modules, then import that. I did that using rsync. This has rather arcane selection requirements, but it can (usually) be made to do what you want.

	cd
	mv python oldpython
	mkdir temppython
	rsync -avz --exclude='*' --include='*.py' --include='*/' ./oldpython/src ./temppython/

Remember that you can do a dry run with rsync by adding the -n or --dry-run option.

I then did the import via

	svn import ./temppython http://servername/svn/username/python/trunk -m "Importing python modules."

If one then does

	svn list http://servername/svn/username/python/trunk

I see

	src/

as desired. The entire directory tree under ~/temppython/src is also present if one looks.

Next, I wanted to copy the whole python directory tree from the 'trunk' subdirectory to a subdirectory off 'branches'. I did

	svn copy http://servername/svn/username/python/trunk http://servername/svn/username/python/branches/release_1.0

This creates a directory 'release_1.0' under 'branches' and copies all the stuff under 'trunk' to it. So if you then do

	svn list http://servername/svn/username/python/branches/release_1.0

one sees

	src/

as before.

The final step is to check out a working copy. I could perhaps do this into the temppython directory I constructed for the import, or even into the oldpython directory, which has all the nonversioned files as well; but I wanted to be quite sure I knew which was overwriting what, so what I did was trash the temppython directory, re-mkdir python, and checkout into that.

	rm -rf temppython
	mkdir python
	svn checkout http://servername/svn/username/python/trunk ./python

Note I also could have done

	svn checkout http://servername/svn/username/python/branches/release_1.0 ./python

if I had wanted to work on the release_1.0 version of the code. The SVN manual also describes how you can switch between different versions.

The final step was to copy all the non-versioned code still in ~/oldpython back into ~/python. I used rsync again:

	rsync -avz --ignore-existing ./oldpython/ ./python/
	rm -rf oldpython

In Chapter 4 of the Redbean book they talk about merging - however (as seems typical for the SVN fellows) from exactly the wrong direction. If I am using the branch just to bug fix and the trunk for development, I do not want to merge the dev changes into the release! Rather the other way around. The way I ended up doing this was from a WC of the trunk rather than of the branch. I then did

	svn merge http://servername/svn/username/python/branches/release_1.0 
	svn update (seems to be required)
	svn commit -m "Merging all branch/release_1.0 changes to trunk."

That's it!