If you're anything like me, you may accumulate a sizable number of branches locally over time. Based on old standards and what I'd consider some good practice, my branch names always follow the same format:


For example, jboyle/1641. While in my case this maps directly to a JIRA issue and is short and easy to type, it isn't very descriptive and after creating a number of branches, it becomes challenging to remember what branch contains what work without looking the issue numbers up in JIRA. Sure I could use more descriptive names for the branches themselves but there are limitations here. For example, you cannot have any spaces in your branch name so you might end up with a name like jboyle/1641-create-new-user-registration-flow. Further, you now have to type all of that each time you need to switch to that branch or perform many operations on it. Enter git descriptions. As of git 1.7, a new flag has been added for branches:

    git branch --edit-description jboyle/1641

This will open vi (or your terminal editor of choice) for you to enter the description for your branch. While this is handy, the only way you can see the descriptions is by checking out your local git config file as they are stored there. Enter a script I found here. The above script, when run within a git repo, will print out all local branchesand their descriptions right next to them as follows:

    * jboyle/1641 Create new user registration flow
jboyle/1576 Fix that one bug in that one place

For my case, I dropped the script into a directory on my machine I use for that very purpose which I'd already added to my .bash-profile. For the uninitiated, however, you can do the same by opening your profile in an editor (I'm using nano in this case because I can):

    nano ~/.bash-profile

You can then add the script itself or its containing folder to your path like so:

    PATH=$PATH:(path to your script or its containing folder)

This all now allowed me to run the script from anywhere without having to specify the path to it and, so long as I'm in a git repo, it'll display the branches and descriptions like shown above. But now we've come so far and fought so hard in the name of better development processes! It would be a shame to forgo taking this to the next level. And by this I mean we should alias all of this in git itself. So let's do it:

    git config --global alias.branches '!sh branch-descriptions.sh'

The above piece of magic adds the command "branches" to git itself and tells git that when this command is run, it should call the script we added to our profile. All of the above now simply becomes:

    git branches

Now we can easily show a list of all our local branches and have their descriptions shown to the right of each branch with a trivial git command. Huzzah! A couple things are worth pointing out, however:

  • These descriptions are purely local and will not be pushed to any remotes as they are stored in your local git config
  • Because of the above, these should not be leaned on as a means of communication/documentation with your development team. They are purely for personal convenience!