How can I document a branch in a remote repository?

Question

I'd like to add a brief description/rationale for the work being done on a branch. Only a sentence or two, but far more than can be communicated via the branch name. Unfortunately, I haven't been able to find a clear way of accomplishing this.

The git branch --edit-description command would seem ideal except that, as it's stored in the repo config, it can't be pushed. The documentation doesn't do much good if it can't be read by anyone else. Two alternatives spring to mind, but both have problems with semantics.

The first is to store the documentation within the repository content. I find this option unappealing both because it "contaminates" the repository content and because it has side effects — particularly when merging.

The other is to use git commit --allow-empty to create a commit with no changes. This still breaks the semantics of the commit, but at least keeps metadata out of the repository.

I'm currently inclined to use the empty-commit technique, but are there other alternatives? Other problems I'm overlooking?

What is the typical way to accomplish this?

Answer 1

I'm not sure this is any better of an option but ...

Presuming this is a branch that isn't going to be rebased, then you could create an annotated tag with a similar name to the branch at the initial branch point, and then use the tag's commit message to describe the branch.

so instead of

git checkout -b my_feature SOME_START_POINT

you would have

git tag -m "Startpoint of the my_feature branch  which is for ...." MY_FEATURE SOME_START_POINT
git branch my_feature MY_FEATURE

Or some other naming scheme like my_feature_start_point, etc.

The information wouldn't be associated with the branch itself, but would be correlated in a way a human could figure out as needed.