Purposeful first commit

“Initial commit” is so uninspiring yet we’ve all committed it somewhere!

I’ve recently found myself creating a noticeable handful of repositories for various projects and it got me thinking: whats in a first commit? It’s the commit that hangs around like a bad smell for years after you make it. It appears in github in that placeholder .gitignore, or in that tiny file that never gets changed. So why think about it?

To me, a first commit helps define what the project intent is. Why are you committing this code? What do you aim to achieve?

This morning I went exploring - whats in a first commit?

How to find the initial commit.

First things first, there can be multiple first commits (well, when it comes to git anyway). For example if you git checkout --orphan you create a ref with no parents. You can also get multiple parentless trees if you merge together repositories - git’s own repository is a great example of this with 7 odd initial commits.

For the purposes of this little experiment I went looking for the most logical first commit using this handy command:

$ git rev-list --max-parents=0 HEAD --format=medium -v

This gives me enough information to make an educated guess on the first commit. If I want more I can just run git show REF.

What’s in an commit?

Every commit made should be useful and detail both what and why a change is made. A message “added X dependency” isn’t as helpful as “X is used for Y”.

Take Chris Beams’ “How to write a commit message” for example. His 7th point highlights a great example of focusing on “what” and “why” rather than “how” you’ve achieved something. The “how” goes in comments alongside your code.

Better first commits

Given that each commit should describe the change it makes, it logically follows that each first-commit should set the stage for what the repository is all about.

Perhaps the best example of this is Linus’ first commit when building git.

Other frameworks including jquery, laravel, vue and jekyll all had more or less useless initial commits. Entertainingly, jekyll did thoughtfully include a README.txt… that was an unmodified template. Some digging into Vue’s initial package.json included the description “Lighter-weight Vue on virtual dom” which I guess is something.