High Level Git Subtree Scripts
September 30, 2010

A while ago in my post Managing Dependent Libraries with Git I talked about some shell scripts that I’d developed to help me to work with the git subtree command.

Since then I’ve updated them quite a bit and rewritten them in python, so I thought I’d revisit them slightly on the blog… There is now just one command line command ‘subtree’ which takes a number of options, like so:

> subtree <command> <tree>

Tree Configuration

The tree parameter is used to look up a configuration file at the path

subtrees/<tree>.subtree

relative to the root of the project.

The configuration files are very simple, and basically just define three variables which the commands use. For example, the ECFoundation.subtree file for my foundation library looks like this:

TREE="ECFoundation"
LOCAL="frameworks/ECFoundation"
URL="git://github.com/samdeane/ECFoundation.git"

The first variable gives a name for the branch that the git subtree system will use to track the module. The second variable gives a location to place the subtree, relative to the root of the local project. The third variable gives the URL location of the repository containing the master copy of the module.

Subtree Commands

Add

> subtree add <tree>

This command grabs a subtree from a remote depot and adds it to your project.

For example, when I first set up a new project and want to import ECFoundation, I first make a “subtrees” directory and copy into it ECFoundation.subtree. Next I cd into the root folder for the project in the terminal, and run:

> subtree add ECFoundation

If all goes well, I end up with a new folder called frameworks/ECFoundation/ containing the latest version of the library.

Push

> subtree push <tree>

This command pushes back local changes to the remote repository that the subtree came from.

For example, if I’ve changed ECFoundation in my project and I want to push my changes back to the master repository, I again cd to the root folder of the project, and run

> subtree push ECFoundation

Pull

> subtree pull <tree>

This command grabs any remote changes to the subtree and merges them into the local project copy.

For example, if I want to pull the latest version of ECFoundation into my project, I cd to the root folder of the project and run:

> subtree pull ECFoundation

Log

> subtree log <tree>

This command runs git log over the local directory containing the subtree.

Commit

> subtree commit <tree>

This command runs git commit on just the local directory containing the subtree. It’s a good idea to commit local changes to the subtree separately from other project changes, so that you don’t end up with weird project-specific commit messages when you push back subtree changes to the master repository for the subtree.

Status Of These Scripts

These scripts are still pretty simple (though more complicated than they were when I started), but they do the job for me.

You can find them on github here.

Comments and improvements to the scripts are welcomed!