Branch descriptions in Git

Is there a way in Git to have a 'description' for branches?

While I try to use descriptive names, working for a while on a single branch sometimes dampens my memory of why I made some of the other topic branches. I try to use descriptive names for the branches, but I think a 'description' (short note about the purpose of the branch) would be nice.

Git 1.7.9 supports this. From the 1.7.9 release notes:

"git branch --edit-description" can be used to add descriptive text
to explain what a topic branch is about.

You can see that feature introduced back in September 2011, with commits 6f9a332, 739453a3, b7200e8:

struct branch_desc_cb {
  const char *config_name;
  const char *value;
};

--edit-description::

> Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. request-pull).

Note that it won't work for a detached HEAD branch.

That description is used by the script request-pull: see commit c016814783, but also git merge --log.

> request-pull is a script used to summarizes the changes between two commits to the standard output, and includes the given URL in the generated summary.

[From @AchalDave] Unfortunately, you can't push descriptions since they're stored in your config, making it useless for the sake of documenting branches in a team.

If you do end up using the README, create a git alias modifying git checkout so that your README is displayed every time you switch branches.

For example, add this in ~/.gitconfig, under [alias]

cor = !sh -c 'git checkout $1 && cat README' -

After this, you can run git cor <branch_name> to switch branch and display the README of the branch you're switching to.

Use git branch --edit-description to set or edit a branch description.

Here is a shell function to show branches similar to git branch but with descriptions appended.

# Shows branches with descriptions
function gb() {
  current=$(git rev-parse --abbrev-ref HEAD)
  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 == $current ]; then
      branch="* \033[0;32m$branch\033[0m"
     else
       branch="  $branch"
     fi
     echo -e "$branch \033[0;36m$desc\033[0m"
  done
}

Here is what gb looks like, shown here as text in case the image rots:

$ gb
* logging Log order details.  Waiting for clarification from business.
  master 
  sprocket Adding sprockets to the parts list.  Pending QA approval.

And as an image, so you can see the colors:

The README suggested by Chris J can work, provided it is setup with a custom merge driver defined in a .gitattribute.
That way, the local version of the README is always preserved during merges.

The "description" for branches is also know as a "comment" associated with that meta data, and it is not supported.

At least, with a README file, you can, for any branch, do a:

$ git show myBranch:README

If your README is at the root directory of your REPO, it will work from any path, since the path used by git show is an absolute one from the top directory of said repo.

There are two popular suggestions here:

1. git branch --edit-description : We don't like this because you can't push it. Maybe I can remember what the branches I created do, but my team sure can't.
2. README file pr. branch. This is a pain during merges: Super-prone to merge conflicts and we'll be pulling in README from branches when we merge feature branches. Diffs between branches are also a pain.

We've decided to create an orphan branches-readme branch. Orphan branches are branches with their own separate history - you may know them from Github's gh-pages branches. This orphan branch contains a single README file. It has contents like:

master:
    The default branch
mojolicious:
    Start using Mojolicious
branch-whatever:
    Description of the whatever branch

It is push-able and merge-friendly. View the README from any branch with:

git show branches-readme:README

Disadvantages are that you need to checkout the weird orphan branch when you want to update the README and the README doesn't auto-update as branches get renamed, come or go. That is fine for us, though.

Do it like:

git checkout --orphan branches-readme
# All the files from the old branch are marked for addition - skip that
git reset --hard
# There are no files yet - an empty branch
ls
vi README
# put in contents similar to above
git add README
git commit -m "Initial description of the branches we already have"
git push origin branches-readme
# get all your original files back
git checkout master

Similary, individual team members can also create their own branches-$user orphan branches describing their own private branches if they want to, as long as they don't push them to the team.

With further tooling this could also be integrated with the output of git branch. To that end, perhaps a README.yaml file could be considered instead of a plain README.

git config --global --add alias.about '!describe() { git config branch."$1".description; }; describe'

Command will define a global option alias.about as shell expression. Running git about <branch> in a repository will display branch's description if set.

Here's a git alias that lets you both set and read descriptions on the current branch:

git config --global --add alias.about '!describe() { msg="$1"; git config branch."$(git rev-parse --abbrev-ref HEAD)".description ${msg:+"$msg"}; }; describe'

Usage/examples:

(develop) $ git about
(develop) $ git about message
(develop) $ git about
message
(develop) $ git about "this is a new message"
(develop) $ git about
this is a new message
(develop) $ git checkout -b test_branch
Switched to a new branch 'test_branch'
(test_branch) $ git about
(test_branch) $ git about "this is the test branch"
(test_branch) $ git about
this is the test branch
(test_branch) $ git checkout -
Switched to branch 'develop'
Your branch is up to date with 'origin/develop'.
(develop) $ git about
this is a new message

Special thanks to @Felicio for the answer that got me started.

Here's a possible implementation of the git branches command Greg Hewgill alluded to:

#!/usr/bin/perl

sub clean {
	map { s/^[\s\*]*\s// } @_;
	map { s/\s*$// } @_;
	return @_;
}

sub descr {
	$_ = `git config branch.@_.description`;
	s/\s*$//;
	return $_;
};
sub indent {
	$_ = shift;
	s/^/      /mg;
	return $_;
};

my @branches = clean `git branch --color=never --list`;
my %merged = map { $_ => 1 } clean `git branch --color=never --merged`;

for my $branch (@branches) {
	my $asis = `git branch --list --color=always $branch`;
	$asis =~ s/\s*$//;
	print "  $asis";
	print " \033[33m(merged)\033[0m" if ($merged{$branch} and $branch ne "master");
	print "\n";
	
	print indent descr $branch;
	print "\n";
	print "\n";
}

Say you want to create a branch

git branch branch-20200328
git notes add branch-20200328 -m "This branch is for whatever"
git notes show branch-20200328

You can attach comments to tags:

git tag -m 'this was a very good commit' tag1

By convention, you could have tags related to your branch names or you could use tag -f to keep a commented tag at the head of your topic branches.

You can use

git config --get-regexp "branch.*.description"

I am pretty sure that feature is not currently supported. I think your best bet is to create a description text file, a README basically, in the branch that has the information that you want.

The selected answer seems like overkill to me. I'd be inclined to maintain a per branch description file that is a normal source controlled file, say master.txt, dev.txt, etc. and if there is an unwieldy number or branches I'd create a hierarchy to better organize it.

Just use:

git config branch.<branch name>.description

To give credit where credit is due: https://glebbahmutov.com/blog/git-branches-with-descriptions/

Use

git branch --list -v

to show an upstream branch:

git branch --list -vv

Add -r to show remotes only or -a to show remotes and local.