git branch naming conventions



~2 min read


267 words

I have a habit of making longer git branch names. I use the branch name as a way to communicate what and why I’m working on something.

For example, beyond just storing the ticket number, I add details like feature vs bug, the name of the section of the code, a terse summary of the problem I’m working on and then which part of that problem.

Here’s an example:feature/826/add-edit/dynamic-inputs/config-file

I’m working on a feature. It’s for ticket 826. It’s part of the add-edit app. The feature is adding dynamic inputs. I’m focusing on the config-file aspect.

One of the reasons I like this approach is that it lends itself to making multiple, smaller feature branches that can be viewed in isolation and/or in a cascading fashion (by changing the target of the branches).

It turns out there’s a peculiar limitation of this approach — I can’t go another level deep without changing the branch.

If I tried to create a new branch feature/826/add-edit/dynamic-inputs/config-file/smaller-piece for example, git would throw an error along the lines of: fatal: cannot lock ref 'refs/heads/feature/826/.../config-file/smaller-piece': 'refs/heads/feature/826/.../config-file' exists; cannot create 'refs/heads/feature/826/.../config-file/smaller-piece'

This is a known limitation of git — branches, despite my use of / are not directories — and git does not allow sub-branches in this way.1

Fortunately, I know how to rename a branch, so if it really mattered - I could have two branches: 2

  1. feature/826/add-edit/dynamic-inputs/config-file/initial
  2. feature/826/add-edit/dynamic-inputs/config-file/smaller-piece

The more you know!


Hi there and thanks for reading! My name's Stephen. I live in Chicago with my wife, Kate, and dog, Finn. Want more? See about and get in touch!