#sub-modules

When you create a new git repo, you get a master branch for free. That's fine in many cases.

Lately I've been using a different branching system for code that's meant to be used as a library (perchance a git submodule or a subtree).

Here's how it works:

Name the branch based on the code's Semantic Version. Examples:

Brand-new code base that's still being written: name the branch semver-0.x.

The x in the branch name denotes a variable, so this branch could house v0.0, v0.1, v0.1.42 and so forth.

You probably could get away with a simple v0.x or even 0.x, but I think the explicitness is helpful indicator for humans and paves the way for machine recognition of semantic branch names.

First version of the code base with a stable public API: semver-1.x.

Upcoming not-yet-stable second version of code base: semver-2.x-beta

Initially I went with semver-2.x-unstable, but I found myself confused when I came back to the project later. Does that mean the code is unstable and crashy? Or just the API is subject to change? Both?

Whereas with beta it was instantly clear to me this branch holds the work-in-progress for version 2.

Second version of the code base with a stable public API: semver-2.x.

There's no master branch.

"master" is too generic a concept and it's an attractive nuisance for submodules. Too often I look at a project, see lots of branches and no way to immediately tell what's going on, so I reach for the familiar: the master branch.

Learning from my own behavior, I see it's important to take away that crutch and force perspective library consumers to understand the project's current state and semver branch structure. Fortunately GitHub makes it easy to select a non-master default branch, so it should be mostly transparent to your users.

Even better, switching the default branch gives the library's author the ability to easy start migrating new users to newer versions of your library (while retaining backwards compatibility with your existing users). For example, update your default branch from semver-1.x to semver-2.x.

My thinking was fuzzy in regards to what's wrong with git submodules. So I finally opened up an editor window and started typing how I think an Ideal Submodule System should work. I wound up with this:

The subproject is copied into the super-project's repo. At least a snapshot of it, if not the entire history. It's a fact of life external resources have a habit of disappearing -- this helps makes your project resilient.

git clone foo is enough. None of this git clone --recursive foo or git submodule init && git submodule update business.

Can easily pull subproject updates.

Can easily push subproject updates.

Can easily handle super-project branching.

Super-project's commits don't wind up in subproject's history.

Subproject's commits don't wind up in super-project's history.

Armed with clearer thinking, I reexamined my options and have settled on Avery Pennarun's git-subtree.

Unfortunately its CLI UX is lacking (you have to specify the subproject's entire remote repo URL each time you pull or push) and Avery hasn't accepted pull requests or budged the project for a year. Fortunately Helmo forked Avery's repo, added .gittrees support and push-all and pull-all subcommands, and generally seems to be keeping on top of pull requests and moving the project forward.

I just started using git-subtree, but so far it's making my life better than before.

P.S. Here's a short primer on using git-subtree.

Update: Hmm, I discovered and turned to Helmo's fork after I got tired of reentering my remote repo URL each time I wanted to push or pull a subtree. Turns out Helmo's fork is currently unstable -- the tests don't pass and there's a definite bug in it when adding a repo as a subtree that doesn't show up until you attempt push it back. So I recommend using Avery's original repo until it's fixed.

Update 2: I fixed the bug and tests are passing in my git-subtree fork. git subtree push-all away!