Print branch description

Question

Git supports an option to the branch command called --edit-description which it states is used by "various" other commands. One command (at least by default) that it is not used by is git branch (when used to simply list the local branches). Is there a way to get git branch to show the branch descriptions (the verbose option looks like it just adds the last commit on the branch)?

To be clear, I'd like something like the following

> git branch
* master      I am the alpha and the omega
  bugfix1     This is the fix to that thing
  future      Transition to the new architecture

Answer 1

I confirm there is no way for now to display the description of the branch with git branch (as opposed to git config, see last part of this answer below).

This thread includes

The coming v1.7.9 will introduce branch description, mainly used in integration process. I think we could make it useful for users who don't extensively use request-pull/format-patch. Showing a short summary along with branch name in "git branch" would be nice.

I agree that it would be nice to give users access to the information even if the branch ends up being merged to the master branch by you and never leaves your repository by itself.

You however are misguided to say "Showing a short summary along...".

The branch description support is to give users a place to record detailed explanation about a branch, similar in size to what you would normally place in a log message of a commit or a cover letter of a series.
There wasn't any convenient place to do so for a branch that is (1) inherently a moving target while it is being developed and (2) is not a good match for tags and notes.

There already is a good place for a brief summary and it is called "branch name". Name your branches just like you name your functions.

The suggested patch "git branch --verbose-format" is not yet completed.

So the script mentioned by poke, remains (with a git alias) one possible solution:

#!/bin/perl
 
$output= `git branch`;
 
foreach my $line (split(/^/, $output)) {
  my ($is_current, $name) = split(/\s+/, $line);
  my $description = `git config branch.$name.description`;
 
  $description =~ s/\s+$//;
  printf("%1s %-22s %s\n", $is_current, $name, $description);
}

---

Philip Oakley suggests in the comments:

You can display the branch description using a git config command.

To show all branch descriptions, I have the alias

brshow = config --get-regexp 'branch.*.description'

, and for the current HEAD I have

brshow1 = !git config --get "branch.$(git rev-parse --abbrev-ref HEAD).description". 

Answer 2

Hit this on terminal. This will display branches with description if your branch has some description.

Step 1:

vi ~/.bashrc

Step 2: Put this

alias git-describe-branches='for line in $(git branch); do 
     description=$(git config branch.$line.description)
     if [ -n "$description" ]; then
       echo "$line     $description"
     fi
done'

Step 3:

source ~/.bashrc

Step 4:

git-describe-branches

OR

for line in $(git branch); do 
     description=$(git config branch.$line.description)
     if [ -n "$description" ]; then
       echo "$line     $description"
     fi
done

Note:

1. Run this in git working directory.

2. Will show description if your branch has description.

Answer 3

I know it has been ages since this was asked, but I just started using branch descriptions and came across this looking for display ideas.

regarding bash script answer: It only prints branches that have a description. I want to mimic git branch output but with descriptions as well.

regarding perl script answer: Formatting fails with longer branch names. It also outputs screwiness if you are in a detached HEAD state.

I had a go in python and this is what I came up with. It solves my issues with the previous answers.

#!/usr/bin/python
import subprocess
import sys


def git(*args):
    return subprocess.check_output(['/usr/bin/git'] + list(args)).strip()


try:
    branches = git('branch').split('\n')
except subprocess.CalledProcessError:
    sys.exit(1)

longest = len(max(branches, key=len))
for branch in branches:
    active = '*' if branch[0] == '*' else ''
    branch = branch.lstrip(' *')
    try:
        desc = git('config', 'branch.'+branch+'.description')
    except subprocess.CalledProcessError:
        print '{:2}{}'.format(active, branch)
    else:
        print '{:2}{:{}}  {}'.format(active, branch, longest, desc)

exhibit A

[user|host ~/git/repo((HEAD detached at origin/master))]% git bd
* (HEAD detached at origin/master)
  branch_a
  delete_this_after_a_little_while_pls_thx_bye    long branch description
  other_branch
  yay_branches_amirite                            PR under review

exhibit B

[user|host ~/git/repo(other_branch_name)]% git bd
  branch_a
  delete_this_after_a_little_while_pls_thx_bye    long branch description
* other_branch
  yay_branches_amirite                            PR under review

exhibit C

[user|host ~/non_git_repo]% git bd
fatal: Not a git repository (or any of the parent directories): .git

Answer 4

I took inspiration from Sahil Gulati and made this:

alias git-describe-branches='git branch | while read line; do 
     description=$(git config branch.$(echo "$line" | sed "s/\* //g").description)
     echo "$line     $description"
done'

Example:

$ git-describe-branches 
bugfixdatum     
feat32     
feat53     
feat56     
* feat57     Projektlista
feat65     
feat72     
feat75     Prevent replacing lager with empty inventering
master     
referens     

This also prints branches without description, and the sed command is because current branch need special treatment due to the asterisk character.

Answer 5

bash command:

eval "git config branch.`git branch --show-current`.description"

if with alias:

alias gs='git status && eval "git config branch.`git branch --show-current`.description"'

Answer 6

Here is a very simple script I'm using. It shows all branches in a nice table highlighting the current one. A prefix could also be passed in the cmd line to show only a subset of branches.

#!/bin/python3

from sys import argv
from prettytable import PrettyTable
from subprocess import check_output
import os
import sys

def format_table(table):
    table.field_names = ["branch", "description"]
    table.align["branch"] = "l"
    table.align["description"] = "l"

def show_branches(prefix):
    table = PrettyTable()
    format_table(table)
    G = "\033[0;32;40m" # GREEN
    N = "\033[0m" # Reset

    try:
        branches = check_output(['git', 'branch']).decode('utf')
    except:
        sys.exit(1)

    for branch in branches.splitlines():
        if prefix not in branch:
            continue

        curr_branch = '*' in branch
        branch_name = branch.strip() if not curr_branch else branch.strip().split(' ')[1]
        try:
            output = check_output(['git', 'config', f'branch.{branch_name}.description']).decode('utf')
            desc = os.linesep.join([s for s in output.splitlines() if s])
        except:
            desc = '---'
        if curr_branch:
            table.add_row([G+branch_name, desc+N])
        else:
            table.add_row([N+branch_name+N, desc+N])

    # Done
    print(table)

if __name__ == '__main__':
    prefix = argv[1] if len(argv) > 1 else ''
    show_branches(prefix)

Answer 7

I can still not find a good solution in 2017.

I came up with another solution though. The first line is required after changing the current branch in order to update the BRANCH_DESCRIPTION file. It just runs the edit-description tool with a "do nothing editor". Then you can simply get the description from the file .git/BRANCH_DESCRIPTION.

(export GIT_EDITOR=':';git branch --edit-description); 
cat $GITREPOSITORY/.git/BRANCH_DESCRIPTION

NOTE:

This might not be documented/stable behavior.

Answer 8

I also took inspiration from Sahil Gulati on my answer. I wanted the script to also include branches that have no description and make it look all pretty like the usual git branch does, so I added some colors and padding.

So you could do something like this.

Create a script, e.g. ~/git-branch-show-descriptions.sh and add execution rights.

branches=$(git branch --format="%(refname:short)")
current=$(git branch --show-current)
no_color='\033[0m'
green='\033[0;32m'
pad="                               "
pad_length=31

for line in $branches
    do
        description=$(git config branch.$line.description)
        padded_line="${line}${pad}"
        formatted_line="${padded_line:0:pad_length} ${description}"
        [ $line = $current ] \
            && echo -e "* ${green}${formatted_line}${no_color}" \
            || echo    "  $formatted_line"
    done

Add the alias to ~/.bashrc

alias git-branch-show-descriptions=~/git-branch-show-descriptions.sh

And source it or restart bash.

source ~/.bashrc

This should show descriptions to all branches that have them and just the name for the ones that don't. The selected branch will be shown in green.

Answer 9

to check branch description in just one line

git config branch.<branch_name>.description