Another reason to use a version control system

I have posted about usefulness of Subversion version control system (svn) a couple of times already, but this morning has prompted me to do another one. Subversion allows you to backup all your valuable data, saving each commit as a separate version. You can see the differences between any two versions, checkout earlier versions, have multiple working copies, etc. If you are a coder, a version control system like svn is essential.

Anyway, this morning made me love svn even more. My main computer is being shipped off for repairs, and I am currently using the boyfriend's old Mac PowerBook G4. I needed to get it setup with all my files so I can continue to do my work. Instead of having to transfer files over one-at-a-time from one computer to the other, I simply did an svn "checkout" of what I needed.

A simple "svn co https:\\my repository path\trunk\Code" and "svn co https:\\my repository path\trunk\References" at the terminal prompt (from within the directory I want to download them to) and I am good to go. All my latest scripts, and my complete reference directory (all the pdfs of all the journal articles I use as references) are now on this computer, within seconds. If I make any changes to these files while on the boyfriend's computer I can simply "commit" them to my svn repository and when I get my computer back, do an "update" and I am all set!

JabRef has also proven to me, once again, its awesomeness this morning. I simply open up my main library.bib bibtex file (just checked out from svn) within JabRef, and there are all my journals, instantly organized and searchable. The PDF links work automatically, simply click on the icon, and the journal articles pops open before me in Acrobat Reader. To see why JabRef is such an awesome reference database software, check my initial blogpost on it here, and the follow-up (showing how, in conjunction with Zotero, it can make organizing and collecting references a breeze) here.

Zotero AND JabRef: how to make both work for you

So yesterday I posted about how I switched over to JabRef reference software, mainly because it allows relative links, but also because it easily lets you see and edit the BibTex entry, which as a LaTeX user, is very helpful. There are two things JabRef does not really do that Zotero does that I find really useful:

1) Zotero can easily capture reference information from a variety of website formats, even if no Bibtex or RIS entry is provided

2) You can drop a pdf directly into Zotero, index it, and then retrieve the reference information automatically, assuming the article is online somewhere

If the article's webpage has a BibTex or RIS entry available for download, you can simply download this and import it into your JabRef database, but I have noticed some journals still do not offer this service (shame on them!)

So this morning I have been happily using Zotero to collect reference information I find online and to auto-generate some entries based off some PDFs I already had. Once I am done, I can export to a RIS file and then import that RIS file to my current JabRef database. My BibTex keys are automatically generated on import, so I simply select the new entries, go to Tools -> Scan Database -> Sync Files and any new PDFs I obtained during the day will be linked to their entry in JabRef.

I keep my Main.bib file that is my current JabRef database inside my folder with all my reference PDFs. At the end of the day, I can simply commit the whole folder to subversion. Everything is not only backed up, but when I checked out the folder on my Windows machine, all my PDF links will work perfectly and I won't have to tweak my database one bit!

I used to hesitate putting all my PDFs in svn, but our school server is pretty huge and the 1 GB or so of PDFs that I have now does not even make a dent. Plus, after hearing from a friend how he lost his whole PDF database and had to go download or even scan (yikes!) all his references again, I decided backing up all my articles in svn was not only OK, but necessary!

Free SVN client for Mac!

Today I went hunting around for a good, and free, svn client for Mac that would allow me to actually view/edit my svn repositories. I am getting a hang of the terminal commands for svn, but I wanted something to make it easy to browse what is in my svn directories. I found that and more in a program called svnX.

svnX allows you to easily view multiple svn directories, use checkout/check in features, browse past revisions, etc. Best of all: totally free.

Here is a screen grab of svnX connect to my svn repository on my school's server:

(svn repository browser, organized by revision number)

When I first opened the program, I got a small error message because the default is to assume your svn binary files are located in usr/local/bin. However, if you installed and run svn via fink, your binary file locations is actually /sw/bin.

Update: To add a file, you can simply drag-and-drop between svnX and the Finder. In order for this to work though, you must drop the file directly onto the folder icon of the repository directory. I spent a few rather frustrating minutes trying to figure this out.

File version control with Subversion

CCOM uses Subversion (svn) on their server to enable folks to have version control on their important documents. What this means is that I can commit a file to my subversion account on the server, and each time I modify the file, a new version will be saved. If I realize I made a mistake or need to go back to a previous copy of the file, I simply "checkout" an earlier version. This is great for constantly changing documents such as source code, html, my thesis proposal, etc. One neat thing is that everytime you "commit" a new version of the document to svn, it only saves the actual changes. Therefore, your memory usage increases only the minimal required amount each time.

To access svn on my Windows machine, I use a program called Tortoise. Tortoise allows me to upload, checkout, update, and commit files easily to svn. For example, initially I uploaded some source code of mine to the repository. It is now safely stored on the server. When I checkout the file from svn, the most recent version (unless I specify otherwise) is dropped onto my local machine. Once I am happy with any edits I make to this local copy, I simply commit the file back to svn. This new copy autmatically gets a new version number (called revision in SVN) and will be stored as the most recent version. The update command is used to update any checked out copies on your local machine to most recent version in the svn repository. This is handy when multiple people are working on the same file.

The only potentially confusing thing thus far is that revision numbering in svn is global. This means that everytime I commit a file, the global revision number for the whole repository increments by one. For example, say I upload a file and svn assigns it a revision number of 25. Then I checkout a file with a revision number 2. Once I edit the file and commit it back to svn, its revision number will update to 26, instead of 3.

A typical svn reposity is set up with three main directories (note this is only a recommended structure):

• trunk - this is the main directory for your files and where you commit regular changes

• tags - a collection of snapshots of the trunk (or a branch) at a user-defined point in time. This basically contains pointer files to specific versions. This is good for a version you want to be able to access quickly. For example, if I used a specific version of my source code to process some data for a publication, I will want to quickly be able to access this exact version.

• branches - active variations of the project compared to the trunk (or even another branch). Branches are good for when you are editing a file already in the trunk, but you do not have a working version yet. Perhaps you are trying out some new addition to your code, and you are still in the testing phase. This is also a good place to store any revisions you have to make to older versions of files in your trunk directory. For example, say I use version X of my code to process data for a paper. Now, a year later, I am on version Z of that code. Someone using version X from my paper finds a bug in it I need to fix but I do not wish to give them version Z yet. I can fix the bug in version X, and commit the new version of that code to the branch directory. That version Z of the code is still my most recent version in the trunk directory.
  

I found a good guide on svn here. This guide is for a specific svn client called Subclipse, but I find it a better tutorial than the one for Tortoise. Now I can stop pestering my poor boyfriend with svn questions over IM.

Oh, I should also note that Windows users who use Cygwin can also use svn via command line .