Git Subtree Merging Guide

I've been investigating ways to incorporate third-party repositories and libraries into my Git projects. Subversion's svn:externals capabilities are one compelling feature for that particular VCS, and few, if any, other VCS systems, particularly the DVCS systems, have a truly viable equivalent. Git submodules aren't terrible, but they assume you want the entire repository -- whereas SVN allows you to cherry-pick subdirectories if desired.

Why might I want to link only a subdirectory? Consider a project with this structure:

docs/
    api/
    manual/
        html/
        module_specs/
library/
    Foo/
        ComponentA/
        ComponentB/
tests/
    Foo/
        ComponentA/
        ComponentB/

On another project, I want to use ComponentB. With svn:externals, this is easy:

library/Foo/ComponentB http://repohost/svn/trunk/library/Foo/ComponentB

and now the directory is added and tracked.

With Git, it's a different story. One solution I've found is using git-subtree, an extension to Git. It takes a bit more effort to setup than svn:externals, but offers the benefits of easily freezing on a specific commit, and squashing all changes into a single commit.

Jon Whitcraft recently had some questions about how to use it, and I answered him via email. Evidently what I gave him worked for him, as he then requested if he could post my guide -- which you can find here.