Introduction

Git allows you to add descriptions to local branches using git branch --edit-description. Branch descriptions provide context about the purpose of a branch — what feature is being developed, what issue it addresses, or its current status. While not widely used, they can help teams keep track of branch purposes in repositories with many active branches.

Setting a Branch Description

1# Set description for the current branch
2git branch --edit-description
3
4# This opens your default editor (like vim or nano)
5# Type a description, save, and close
6
7# Set description for a specific branch
8git branch --edit-description feature/user-auth

Reading a Branch Description

1# Read the current branch's description
2git config branch.$(git rev-parse --abbrev-ref HEAD).description
3
4# Read a specific branch's description
5git config branch.feature/user-auth.description

Create an alias for convenience:

1# Add alias to read current branch description
2git config --global alias.desc '!git config branch.$(git rev-parse --abbrev-ref HEAD).description'
3
4# Usage
5git desc

How Git Stores Descriptions

Branch descriptions are stored in .git/config as branch configuration:

[branch "feature/user-auth"]
    description = Implementing OAuth2 login flow for Google and GitHub providers.\nJira: AUTH-123

They are local only — descriptions are not pushed to remote repositories.

Practical Use: Branch Listing with Descriptions

Create a script to list branches with their descriptions:

1#!/bin/bash
2# Save as git-branches (and add to PATH for 'git branches' command)
3
4for branch in $(git for-each-ref --format='%(refname:short)' refs/heads/); do
5    desc=$(git config branch."$branch".description)
6    if [ -n "$desc" ]; then
7        printf "%-30s %s\n" "$branch" "$desc"
8    else
9        printf "%-30s %s\n" "$branch" "(no description)"
10    fi
11done

Output:

1main                           (no description)
2feature/user-auth              OAuth2 login for Google and GitHub
3fix/memory-leak                Fix connection pool leak in DB module
4feature/dark-mode              Dark mode theme support (Jira: UI-456)

Branch Descriptions in merge/request-pull

Git uses branch descriptions automatically in certain commands:

1# git merge --log includes the branch description
2git merge --log feature/user-auth
3
4# git request-pull includes the branch description
5git request-pull origin/main https://github.com/user/repo feature/user-auth
6
7# git format-patch cover letter uses the description
8git format-patch --cover-letter origin/main

Branching Strategies

Branch descriptions are useful within these common branching strategies:

• Gitflow Workflow: A branching model that leverages feature, release, and hotfix branches to streamline development. Descriptions help distinguish between multiple active feature and hotfix branches.
• GitHub Flow: A simpler, more modern strategy that uses branches primarily for feature development, always keeping the main branch deployable. Descriptions can note the linked PR number.
• Trunk-Based Development: All developers work on a single branch (often the main) with short-lived feature branches merged in rapidly. Descriptions help clarify the purpose of very short-lived branches.

Alternatives to Branch Descriptions

Since descriptions are local-only, teams often use other conventions:

Branch Naming Conventions

1# Encode purpose in the branch name
2feature/AUTH-123-oauth-login
3bugfix/MEM-456-connection-pool-leak
4hotfix/SEC-789-xss-in-comments
5chore/upgrade-react-18

PR/MR Descriptions

GitHub, GitLab, and Bitbucket provide PR descriptions that are shared with the team and linked to the branch.

Git Notes

1# Attach notes to a commit (shared via push)
2git notes add -m "This commit addresses AUTH-123"
3git notes show HEAD
4
5# Push notes to remote
6git push origin refs/notes/commits

Common Pitfalls

• Not shared remotely: Branch descriptions are stored in .git/config and are not pushed to remote repositories. Team members will not see your descriptions.
• Lost on branch deletion: When you delete a branch, its description is also removed. There is no history of branch descriptions.
• Editor requirement: git branch --edit-description opens a text editor. Set your preferred editor with git config --global core.editor "code --wait" or similar.
• No built-in listing: There is no native git branch flag to show descriptions alongside branch names. You need custom scripts or aliases.
• Multiline descriptions: Descriptions can be multiline, but git config reads only the first line by default. Use --get to retrieve the full description.

Summary

• Set branch descriptions with git branch --edit-description
• Read with git config branch.<name>.description
• Descriptions are local only — not shared when pushing to remotes
• They appear in git merge --log, git request-pull, and git format-patch
• For team-wide context, rely on branch naming conventions and PR descriptions instead