Versioning Codea Projects with Git

Codea is a programming environment for the iPad that, uniquely, runs on the iPad itself. It gives you a Lua interpreter, an editor, a simple graphics API inspired by Processing, some bleepy-bloopy sound output and access to the accelerometer and multitouch input. It's great fun to play with and people have pushed against it's limitations to write some really impressive things.

One thing Codea doesn't give you is version control. You don't even get undo/redo! This is a real pain when you're experimenting with arty graphics algorithms or tweaking gameplay parameters.

So, this is a brief note on how to use an editor running on Linux (I use Ubuntu 11.04) to edit Codea code stored the iPad and version the code with Git.

  1. Pull down the latest code from the Git master branches of libimobiledevice and ifuse from and compile them.

  2. Install unionfs-fuse. It's in the Ubuntu software repositories, so no Git and compiling required.

  3. Create an empty directory in your Linux filesystem to act as a mount point for the Codea directory on the iPad:
    % export CODEADIR=~/codea
    % mkdir -p $CODEADIR
  4. With the iPad plugged into a USB port of the Linux computer, we can now mount the Codea documents directory with the following command:

    % ifuse --appid com.twolivesleft.Codify $CODEADIR

    From the Linux machine we can edit the Codea files stored on the iPad. Each project is stored in a subdirectory with the .codea extension. Inside that are the Lua source files and some plist files. For example:

    % ls $CODEADIR
    ABCTune.codea       Controllers.codea    FlightPath.codea
    GrumpyPigs.codea    HersheyFont.codea    
    % ls $CODEADIR/ABCTune.codea
    Data.plist          Info.plist          Main.lua

    However, if we create any files in Codea's directories that it does not expect to see, Codea will delete them. Unfortunately this includes the directories created by Git. So we need to overlay local directories containing Git metadata and the Codea directories on the iPad. This is where unionfs-fuse comes in...

  5. For each Codea project we want to manage under version control, create a separate directory structure to hold the version control information and any other files.

    % export PROJECTDIR=~/GrumpyPigs
    % mkdir -p $PROJECTDIR

    Then create an empty subdirectory under that to be a mount point at which to overlay the Codea project's directory stored on the iPad:

    % mkdir $PROJECTDIR/src
  6. Now, we overlay the Codea project directory onto the directory structure we just created, making it's contents appear to be in the src/ subdirectory.

    % unionfs-fuse $CODEADIR/GrumpyPigs.codea=RW $PROJECTDIR/src
  7. Now we can start versioning our project with Git!

    % cd $PROJECTDIR
    % git init .
    % git add src/
    % git commit -m "first commit"

    Note: you can use any VCS in place of Git, as long as it does not store its metadata in every directory of the project. That means Subversion is not an option.

  8. To safely unplug the iPad we must unmount the project overlay and the Codea directory before we pull the USB:

    % fusermount -u $PROJECTDIR/src
    % fusermount -u $CODEADIR

Some shortcomings & puzzles:

  1. I first tried to overlay the Code project directory with the mount --bind command, but it didn't work, so I used unionfs-fuse instead. If you know why/why not, please drop me a line in the comments.

  2. I'm sure there are FUSE or mount options that would mean I don't need sudo to unmount the directories when unplugging the iPad. I've not had the time to find out. If you know more than me, please drop me a line in the comments.

    Fixed: use fusermount -u rather than sudo umount to unmount the filesystem.

Copyright © 2011 Nat Pryce. Posted 2011-12-11. Share it.