In my last post, I explained why using Tinderbox properly with version management software has been tricky. In brief, two Tinderbox files can be identical in content, and yet have a very different file structure. That has confused tools like git and Subversion, which expect changes in the files to indicate changes have been made to the document.

This post will explain how to use Git to back up and track the version history of your Tinderbox documents. In the post after this one (which I will post this weekend), I will demonstrate how to collaborate using Github, Unfuddle, or some other online repository. The final post in this series will look at specific options for using Tinderbox with Git.

Preface: Ways to Share and Back Up

• Finder Litter was my strategy before GIt. This involved making copies of documents at sporadic times, at various points of development.
  • The folder for this weblog is littered in this way. I have "Lifebox", "lifebox copy", "Lifebox Copy.tbx", "Lifebox copy 1", "Lifebox.bak", "Lifebox.orig", "Lifebox-xrefered-to" , and a "baks" folder full of other copies
  • These backup copies get messy, and it's hard to tell from the "Date Modified" which ones are older, since the date changed when I copied the files from my old laptop
  • These backup copies no longer work, since they are now out of sync with the current version of the template files, which are now themselves cluttered about all over
• Time Machine, which comes with every Mac, will back up your files automatically. This is great. But it has some downsides:
  • There is only blunt control over what goes into the archive
  • You don't control when things go into the archive. While you may wish to archive things at certain key points in development, Time Machine will do it on a regular, timed basis. You might really wish to go back to where you were at midafternoon, but Time machine will take you back to the night before
  • To address the timing issue, you have to resort to Finder Litter, which will just get compounded over numerous Time Machine backups
  • There is no facility for sharing
  • Time Machine is OK-ish for personal backups. But it won't help you with sharing materials or working with documents which you live with over time
• At $99 a year for 50GB and a free 2GB option, Dropbox seems like a great way to back up and share your files-- so long as you're online with a good connection when you need to work on things
  • If you look at the instructions in this post and think that they're maybe too techie for you, Dropbox is a fine alternative.
  • note: the recent Tinderbox fix over line order will likely lead Tinderbox files to take up less space on Dropbox
• Git is "a free & open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Every Git clone is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server." With git, you can:
  • Keep a version history of your things on your local computer
  • Decide which things are important to backup and version
  • Decide when the snapshots are made
  • Keep related files in sync
  • Create branches (of things like templates), in which you experiment with something you may not wish to keep, and then merge them into the main history when you decide to keep it, or just revert to the main history if you decide against it.

Step 1: Obtain Git

There are two ways to install Git on OSX:

• Git OSX Installer (Leopard Only)
• MacPorts (Recommended, but very techie)
  • MacPorts makes available a large number of useful GNU and other Free / Open Source software on your computer. To install, you will have to install Apple's XCode first, then run the MacPorts installer. You will need to sign up for an Apple Developer Connection account (quick and free) to access XCode.
  • After you hae installed MacPorts, run the following command from a Terminal:

You should download GitX, a very helpful tool.

You will definitely want to get "Shell Here", by John Daniel and Marc Liyanage, since you will probably end up using the Terminal at some point or other. This button, when you add it to the Finder, will open a Terminal in the current finder window (installation explained here).

Step 2: How Git Works

(note: why read my blog post when you can read Swicegood's helpful book, Pragmatic Version Control Using Git ?)

Most of what you need to do will happen within GitX. There is also a helpful article on the GitX website, which is slightly more helpful for people who already have repositories.

• First, initialize a repository. From GitX, select File->New and select the folder you wish to track.
  • Git will store all of its version history hidden inside this folder.
  • If you delete this folder, your backup is deleted
  • If you copy this folder somewhere, your backups and version history also gets copied
• Next, commit files to the repository, which tells git which files you want to backup and track. To do this, you:
  • Click the "commit" button, or select View->Commit from the menu. GitX will switch to "commit view" (click to see screenshots, with annotations).
  • To preview a file before committing it, just click on the file. Tinderbox files probably seem incomprehensible unless you know XML.
  • If you already have a repository and have already committed files, GitX will highlight files which have changed, let you compare differences, and decide if you wish to commit those changes.
  • After previewing the files, drag them into the "staged changes" area to show which ones you wish to commit.
  • To help you find your changes later, Git permits you to add comments to your actions. My comment here is probably more verbose than necessary.
  • Click "Commit" and your files will be added to the repository
  • If you go back to "History View", Git will show the history of your archive much like stops on the rail line.
• Whenever you want to commit something new to the archive, or just tell Git to update its archive to the most recent version of a file:
  • Use the File->Open menu to select the folder
  • Select "Commit view." Git will show all of the files which have changed, or been added.
  • Repeat the steps you used to commit your files initially.
• If you want to recover a file from your history, simply drag it from the "History View" into the Finder. If you want to use that older version in your archive:
  • Commit the current version
  • Overwrite the current version with the historical one you just dragged into the Finder, and commit again. Git will then archive the file you decided not to keep, while also letting you start again from an older version.

This post is long enough, and I need to prepare for Hypertext 2009. I will write from Milan late next week about how to collaborate using Git. There will have to be a fourth post about how to use Tinderbox with Git.