docs:git:branch_descriptions [hartungdesign.net wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== branch descriptions ======
Descriptions are a very helpful way to identify what a branch was created for since it is common to have branches that are left untouched for long periods of time, or that use tracker numbers as the names.

If using a newer git, you can set a description with this:<code>
git branch --edit-description
</code>

If your version of git does not allow this parameter, you can still add it like this:<code>
git config branch.mybranchname.description "here is a detailed description of the branch"
</code>

To make this highly useful, it is best seen when running a command such as ''git branch''.  However, even the versions of git that support adding a description do not show the description in the output.  To remedy this for now, we change our common bash alias ''gb'' into a function that is more informative.  Put this in your ''~/.profile''<code bash>
# Shows branches with descriptions
function gb() {
	branches=$(git for-each-ref --format='%(refname)' refs/heads/ | sed 's|refs/heads/||')
	for branch in $branches; do
		desc=$(git config branch.$branch.description)
		if [ $branch == $(git rev-parse --abbrev-ref HEAD) ]; then
			branch="* \033[0;32m$branch\033[0m"
		else
			branch="  $branch"
		fi
		echo -e "$branch \033[0;36m$desc\033[0m"
	done
}
</code>

Here is some idea of what it looks like so this will make sense.  Imagine how much extra work it takes when using efficiently named issue numbered branches without having descriptions right in front of you.<code>
$ gb
  master
  issues/432
  issues/975
* issues/1053 using jquery ui sortable for custom columns
</code>