Take the 2-minute tour ×

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.

share|improve this question
I had a similar problem. I use that file to document branches and why they exist (among other things). –  themis Jan 23 '10 at 1:13
Why do you not name the branch according to your idea ? Im not sure but a feature should be describeable in a compound word –  fyr Jul 20 '11 at 12:16
This would be a really useful feature. git branch -a could show the descriptions next to the branch names. Maybe git notes will support notes on branches as well as commits in the future? –  jhabbott Oct 31 '11 at 13:55
add comment

10 Answers

up vote 66 down vote accepted

Git 1.7.9 (currently rc1) 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;



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.

share|improve this answer
Is there a way to show the description of a branch? –  Owen Apr 3 '12 at 18:38
@Owen: The only way I know of at the moment is to use git config branch.topic.description to show the description for branch topic. It's stored in the .git/config file. –  Greg Hewgill Apr 3 '12 at 19:23
@GregHewgill Thank you. With a few aliases that's actually not a bad way to view it. Now if only git branch would show the descriptions in the list... –  Owen Apr 4 '12 at 20:10
Here goes a simple script to show branches and their description: gist.github.com/2658582#. Just create a Git alias for it (i.e., something like branches = !/path/to/script). Feel free to use the the script as you like. –  Pedro Rodrigues May 11 '12 at 9:26
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. –  Achal Dave Aug 8 '13 at 16:48
show 3 more comments

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() {
  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"
       branch="  $branch"
     echo -e "$branch \033[0;36m$desc\033[0m"
share|improve this answer
add comment

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


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

sub descr {
    $_ = `git config branch.@_.description`;
    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";
share|improve this answer
Thanks for this. –  joon Oct 24 '12 at 18:27
add comment

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.

share|improve this answer
Cool. This is useful. Thanks. –  Noufal Ibrahim Jan 21 '10 at 11:39
add comment

I don't think so. If you want, you can always maintain a file within the branch saying, branch_purpose.txt or something.

share|improve this answer
add comment

If you do end up using the README, create an 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.

share|improve this answer
+1. That's a nice tip but don't you mean .gitconfig rather than .gitignore? –  Noufal Ibrahim Nov 3 '10 at 10:39
That I do. Thanks! –  tta Nov 3 '10 at 10:47
Interesting tip (no idea why it was downvoted). +1 –  VonC Nov 3 '10 at 11:55
I hate it when people downvote without a reason. The point of the whole exercise to to learn and improve. –  Noufal Ibrahim Nov 3 '10 at 16:21
For me $1 variable is not working — it contains nothing. I don't know why (I'm using version 1.7.11-msysgit.1). I'm using $0 instead. And everything is fine. –  shytikov Jul 18 '12 at 7:26
add comment

Since branches are mostly illusional in git (just a local handy name for a commit that you might want to use as a parent someday), why bother? Sounds like you need some other meta information somewhere.

share|improve this answer
Well, I'm not totally sure. I sometimes end up with branches the reason for which I've forgotten. And extra 'info' field would be nice. –  Noufal Ibrahim Jan 23 '10 at 16:15
add comment

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.

share|improve this answer
this is not ideal because it does not track the head of the branch –  AndyL May 27 '11 at 19:42
add comment

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.

share|improve this answer
Then you'd have to worry about merging these files to every other branch, or remember to use git show master:dev.txt which is not any simpler than the selected answer. –  Sridhar Ratnakumar Dec 23 '10 at 22:40
add comment

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.

share|improve this answer
I'd have to worry about (not) merging this file across branches. Wouldn't I? –  Noufal Ibrahim Jan 21 '10 at 10:40
-1: not correct any more, see accepted answer –  Kasper van den Berg Jul 13 '12 at 9:44
@KaspervandenBerg: Maybe just leave a comment instead of pulling out the -1-card, then wait some time, and if the asker is not willing to change the post, but you see he/she/it visited this site in the meanwhile, spell it. Or do you regularly check all your answers given to see if they are still correct? –  phresnel Aug 15 '12 at 8:12
@phresnel: good point; my intention was to help future askers of this question and have good anwers go to top and incorrect ones to bottom, it was not to "punish" Chris J and cause him to loose reputation. Unfortunately the site says my vote is locked :(. –  Kasper van den Berg Aug 15 '12 at 10:26
@KaspervandenBerg: I was a bit quick to suspect you of punishing, sorry. –  phresnel Aug 15 '12 at 11:06
add comment

Your Answer


