In tonight’s post I want to show you a feature of Git which, in my experience, developers rarely use: branch descriptions.
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
--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.
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!