Using Branch Descriptions in Git

In tonight’s post I want to show you a feature of Git which, in my experience, developers rarely use: branch descriptions.

The What

A ‘branch description’ is exactly what is sounds like: a description of a branch. Similar to a commit message or note (as in git notes) the description is a chunk of text associated with a branch. Semantically it is where you can describe and document the overall purpose of a branch, what benefits it provides, the over-arching changes it introduces to a project, and so on. This is an extra level of documentation which enriches the repository history, assuming the descriptions appear in merge commits, but I’ll get to that a little later.

The How, for Developers

git branch --edit-description

This will open your editor so that you can type down the description for whatever branch you’re on. That’s all you have to do. Afterwards whenever you push your branch you will also push the description along with it.

The How, for Maintainers

Branch descriptions are only truly useful when they appear in the history of a repository. If a developer uses git request-pull then Git will automatically include the branch description if it exists; however, I rarely see people use this command, especially with regard to services like GitHub—honestly I have never even tried git request-pull with GitHub, so after finishing this article I’m going to try that out.

The first thing you need to do is tell Git to include branch descriptions when merging. To enable this globally:

git config --global merge.branchdesc true

Then when merging a branch you can include its description in the merge commit message by giving the --log option to git merge. This will include not only the branch description but a oneline description of each patch in the branch, e.g. git shortlog. However, Git will not include branch descriptions for fast-forward merges, even if you use --log. This is one of the main reasons I recommend maintainers avoid fast-forward merges. You can force Git to create a merge commit including the branch description with the following command:

git merge --no-ff --log --edit name-of-the-branch

The --edit flag is not necessary but personally I recommend it so that you can change the formatting of the message of trim the output if you like.

If you do not want to type out those options every time then you can configure Git to use certain options for any merge to a specific branch, which I find particularly useful for the master branch of projects. For example:

git config branch.master.mergeOptions "--no-ff --log --edit"

After running that in a project repository, any use of git merge while on the master branch will behave as if given the options --no-ff --log --edit. Being able to configure this per-branch is very useful in my opinion.

Conclusion

That’s pretty much it! Git can also include branch descriptions when you create a series of patches to send via email, but that’s an uncommon workflow in my experience so I’m not going to get into those commands. I recommend developers always use git branch --edit-description to provide information about their branches, because even if that information doesn’t make it into the repository history it can still be useful to the developers themselves as a means to document one’s goals and intentions.

So go forth and describe your branches!

Advertisements

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s