Idiomatic Git
Conventions for Branching and Committing
Words matter. As writers of code, we realize that words not only allow us to communicate with other people, but we also create systems (programming languages) that allow us to communicate with computers using words. We solve problems with computers and we want to create systems to accommodate that. We should never be slaves to these systems, but I believe we should seek to create them when possible. With this in mind, I propose the following system for idiomatic Git naming conventions to facilitate programmatic problem solving (create tools that parse commit messages, etc) and also enhance developer experience by lowering cognitive overhead. We’re used to “thinking like computers” so let’s double-down on this value. Please note that all ideas contained herein are stolen and none are my own.
Git branch names should follow a clear and specific convention: type/topic/meta. These components increase in specificity as you move right. type should come from a loosely-defined set of types that can pertain to any Git repository. topic should be a commonly reusable topic/feature/interface within a specific Git repository. meta should be a pithy description of the specific change being made; be reusable when possible.
Here is a suggested list of types:
Hopefully you get the point that I’d rather be inspirational than prescriptive. Find types that work for you and your team. The types I suggest are common and you’ve probably seen them used before.
The title of the commit message should be a function of the branch name. Given the branch name chore/proj/init, I propose that the commit message title should be chore(proj): [init] (or, more generally speaking, type(topic): [meta]). If necessary, a pithy “human-readable” description can be provided, as in chore(proj): [init] Initial Project Commit. As always, additional detailed information should be included in the commit message body when needed. Some other examples of common commit messages:
The goal of these conventions is to make life easier. If you think they’re crazy, don’t follow them. If you think they’re interesting but could use some changes, make them and tell me about them! By God, if your team thinks they’re crazy drop it! The point is: think about how you can infuse maximal information into your Git conventions with minimal overhead. These are some of my suggestions. Happy committing!
I had seen these types of terms floating around but had never seen them codified until I joined FactSet Research Systems, and I would like to give special credit to my former co-worker Hutson Betts who took a lot of initiative to advance standards such as this at FactSet. I hate the fact that when people ask me about these conventions I don’t have a handy resource to point to, so in the spirit of advancing standards like Hutson I created this document.
After posting this in various channels, I was made aware of the Conventional Commits specification, which is an excellent codification of some of the concepts described herein.