health care, road trips, tech talk, occasional rant

how I use Subversion

I’ve had the love/hate affair any industrial-strength developer has with source control for, geez about fifteen years now.

  • You love it because it sure saves your ass every now and then, and you love that little clunk! of goodness you get every time you commit some changes.
  • But gawd, what a pain in the ass it is to set up and administrate, and even to use for something even slightly out of the ordinary.

At Autodesk I learned CVS in the mid 90’s when we were still Unix-based, then learned SourceSafe when we took the painful step of converting development to Windows and thus assimilating into the Microsoft Borg.

On my own in the 00’s I used CVS on cloudyhands and on my Windows laptops and on the major projects I worked on, but now I’m on a MAC and starting a new project, so it was time to do a little googling and see if perhaps there was a better way, heading into the second decade of the new millenium.

Thus I found Subversion (SVN). After I installed it and put the effort into learning it, I noticed that there is now something called GIT, an even newer, even more warm and cuddly source control system, but I’m on the Subversion path for now.

  • I do not remember how I originally loaded it on the laptop, but instructions were on the Apple site and were real easy.(*)
  • create my local repository by entering from my root directory svnadmin create jfsvn, which creates duh… directory jfsvn
  • My host admin has a “one-click install” for it, so that was real easy also :)
  • I did have some wierdness with Finder which freaked me out for a half-day, until some lovely person on some tech board gave me the 411 that I must have inadvertently installed some little helper app for using the two (Finder and SVN) apps together.  I googled further and found out how to kill that  sucker – it involved going to some /bin directory and using sudo to edit a root-access file – and all was back to “normal”. (*)
  • So I am content to use SVN simply via shell commands in a terminal window, or via the Textmate Subversion bundle, which is only a very thin layer around the shell commands. No doubt the Finder integration is awesome, but the episode above kinda traumatized me.

(*) Apologies for the appalling lack of useful detail here, if I had started this self-documenting binge four months ago I would have all the ‘deets.

Here’s how I organize my code.

On the Mac, the standard place put your local server files is in the Sites directory.  I am user jf on my machine, so that is /Users/jf/Sites.

I decided to put each major component of this new development in a separate folder directly under Sites, so:

/Users/jf/Sites/include        the ever-useful folder of shared code
/Users/jf/Sites/resume         my resume, the code destined for here
/Users/jf/Sites/cloudyhands    my new home page and main site, here
/Users/jf/Sites/wfuser         whufu user-view
/Users/jf/Sites/dev            whufu development view, where I do all that inter-connecting

Now, my Sites directory is full of tons of other stuff accumulated over the years, none of which I wish to put under source control, so again a little googling led me to the following simple recipe:

  1. to be safe, copy the directory, say resume – Mac OS has the handy Apple-D key, which creates resume copy.
  2. now go to the original (although the copy would work just as well) and remove everything you don’t want to have under control – for me, that’s the images, other binary files, the Textmate project file, temp files, and possibly data files.
  3. import the directory.  From my Sites directory I enter: svn import resume file:///Users/jf/jfsvn/resume -m "Initial import" – Note that SVN likes to operate on urls, which gives it a nice syntactic uniformity between local and network usage.  So this command says to import the folder /Users/jf/Sites/resume (the first instance of “resume”) into the repository directory /Users/jf/jfsvn/resume, using the standard URI syntax for a local path (prepending with “file://”).  This is recursive by default, so should also be cleaned in step 2, and magically imported here.
  4. prove you got ’em if you want -  svn list --verbose file:////Users/jf/jfsvn/resume
  5. delete (or simply rename for even more safety) the original directory
  6. checkout what you just imported, from the Sites directory enter: svn checkout file:///Users/jf/jfsvn/resume resume – which re-creates the parts of the original directory that you wish to control.
  7. copy back the images, etc from the copy from step 1, and you are in business!

So I end up with a handful of semi-distinct source trees. I never figured out how to do this in CVS, so I am much happier. Some commands work globally, so (from Sites), svn diff shows all changed files in all directories, and svn status lists all files in Sites, and all files in the commited directories, but NOT files in uncommitted subdirectories, which is duh, just what you would want!  [UPDATE] Well, I just noticed that this is true only for the two folders I started with – dev and include.  The other folders tacked on with my handy steps above show up as “?”s in the Sites status listing.  You must operate on them by name, e.g. svn diff wfuser.

More small things:

  • As with CSV, you can add a single file in an already commited with svn add, then svn commit, likewise, the official way to remove a file is to actually delete it from the directory, then commit it, which makes the removal official to SVN.  I usually mess this one up somehow, so I hate to remove files.
  • The easy way to commit is with the -m “comments” option. Otherwise it will pop up an emacs window for your comments, and running into emacs ruins my whole day. :)
  • svn status on a directory gives you the status of every committed file, with “?” for files unknown to SVN.  I use this every now and then to make sure I have “vaulted” everything I should.