How can I document a branch in a remote repository?
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.
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.
- How can I insert a commit before rebasing?
- Specify the 'origin/master' part in a git push
- How to create a new empty branch for a new project
- What's a good process for managing persistent codelines in git?
- Not able to perform git checkout on local with origin/master
- GIT - How to know the branch a branch branched from?
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?
One Solution collect form web for “How can I document a branch in a remote repository?”
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.