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.

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?

  • Git: can't switch to new remote branch
  • Remove a tracking from a git branch
  • How to remove an in-between merge in git?
  • Git pull/push error: RPC failed; result=22, HTTP code = 408
  • git push --tag keeps commits
  • Git HEAD referring to branch vs to commit
  • How to move a subdirectory from a branch in one git repository to a branch in a different repository, preserving history?
  • How do I move a commit between branches in Git?
  • 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.

    Git Baby is a git and github fan, let's start git clone.