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.
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.
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.
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.
Just use:
git config branch.<branch name>.description
To give credit where credit is due: https://glebbahmutov.com/blog/git-branches-with-descriptions/
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.