Git Branch Naming Conventions

So you’ve decided to use feature branches as a way to manage the development of your app. Congratulations! (If not check out this article on the merits of feature branches and how to accomplish them in git).

You’ve set up the structure of your core branches and how they will be deployed to your various environments. The time has come to start work on a new feature. You checkout the latest version of develop and type git checkout -b ... but what do you name it?
The problem

It’s a problem as old as programming itself. As Phil Karlton said,

"There are only two hard things in Computer Science: cache invalidation and naming things".

If you’re working on a team, and even if you’re not, without some kind of style guide, you’re going to end up with branch names like:

  • cool-new-feature
  • bugfixForThatOneIssue
  • story_123456

If you’re like me, names like that bother you and you think to yourself, “there must be a better way to do this”. After Googling around for ideas and turning up empty-handed, I set out to create my own naming convention for git branches.

The Goals

Like many startups, or complex software projects, we (at ASAPer) use a set of tools to help us manage our development cycles. Currently, we use Pivotal Tracker for story tracking, git for source control, and GitHub as a central repository to do pull requests, code review and merging.

When I set out to codify a style guide for branch names, I wanted the naming convention to accomplish the following goals:

  • Be easy to read (I can tell what the branch is from a list of branches)
  • Be tied to story management software
  • Be easy to see if it’s a feature branch, bug fix etc
  • Be easy to type

The Solution

The naming convention I settled on has three sections:

  1. Story Type
    • ft == Feature
    • bg == Bug
    • ch == Chore
  2. Short Summary: 2-3 words about what the branch contains
  3. Pivotal Tracker ID

These three sections are separated with hyphens. The end result looks like this:

{story type}-{2-3 word summary}-{pivotal tracker id}

If we were working on a chat app, like WhatsApp for example and our story was a feature which gives the user the ability to send their location. We would start with a pivotal tracker story that looks like this:

We would go ahead and mark it as started and copy the ID. Now that we have all the necessary components, we can check out a feature branch with the following name:


Besides achieving our goal of tying a pull request back to its story in pivotal tracker, using the id serves a less-obvious purpose: it forces us to mark the story as in progress when we go to start a new branch. It also forces us to make all feature branches relate to a story.

So much for being easy to type…

This solution hit 3 of my 4 initial goals, but what about being easy to type? We found a few ways to improve the process of working with these somewhat unwieldy branch names.

Tab-complete git branches

By downloading the git-completion bash script and adding a few lines to your .bashrc file, you can tab-complete branch names just like you can with file names.

Toggle between git branches

It’s pretty common to flip back and forth between a main branch, like develop, and a feature branch. This is trivial using git checkout -, or gc - if you have gc aliased to git checkout like me.

Copy and paste

If all else fails, copy and paste is your friend. Just make sure you’re using a terminal with good support for the system clipboard.

So that’s it, that’s how we are currently managing our branch names and it’s working great for us. I’d love to hear about any other naming conventions out there.

Andrew Allen

Author of, Software Engineer @Munchery, Former startup founder.

comments powered by Disqus