git 你如何注释一个分支？

How do you annotate a branch?

提问by William Pursell

Is there any way to annotate a branch? It would be nice to be able to do something like:

有没有办法注释一个分支？能够执行以下操作会很好：

$ git notes add branch-name -m 'This branch is for whatever'

but that of course is not terribly helpful, since the note applies to the current head of the branch rather than the branch itself.

但这当然不是很有帮助，因为注释适用于分支的当前负责人而不是分支本身。

An easy workaround is to drop a README.branch-name in the repository, but that seems clumsy. Slightly more elegant is to have an orphaned branch containing nothing but README.branch-names. I'm looking for a way to record what the purpose of the branch is other than just putting it in the commit message for the "first" commit of the branch. I put "first" in quotes because it's not always clear what is meant by that, which is the reason it is inconvenient to put the discussion in a commit message. It's often difficult to find the commit in which such a message is recorded.

一个简单的解决方法是在存储库中删除 README.branch-name，但这似乎很笨拙。稍微更优雅的是有一个只包含 README.branch-names 的孤立分支。我正在寻找一种方法来记录分支的目的，而不仅仅是将其放入分支的“第一次”提交的提交消息中。我将“第一”放在引号中，因为它的含义并不总是很清楚，这就是将讨论放在提交消息中不方便的原因。通常很难找到记录此类消息的提交。

采纳答案by Brian Phillips

This would be a totally different approach than git notebut you could use git configfor this functionality.

这将是一种完全不同的方法，git note但您可以使用git config此功能。

$ git config branch.<branch-name>.note 'This is what this branch is for'

This can be aliased to make the interface simpler (I'm guessing this can be improved but this is what I use):

这可以别名以使界面更简单（我猜这可以改进，但这是我使用的）：

$ git config alias.branch-note '!git config branch.$(git symbolic-ref --short HEAD).note $( if [ $# -gt 0 ]; then ; fi)'

This allows you to set the branch note like so (make sure you quote the note):

这允许您像这样设置分支注释（确保引用注释）：

$ git branch-note 'This is what this branch is for'

You can then retrieve the current branches note like this:

然后，您可以像这样检索当前的分支注释：

$ git branch-note
This is what this branch is for

As an added benefit, config entries defined under the branch.<branch-name>namespace will follow branch renames and be automatically cleaned up if you delete the branch later. These superfluous config entries will only persist as long as the branch exists, at which time they will be automatically deleted.

作为一个额外的好处，branch.<branch-name>命名空间下定义的配置条目将遵循分支重命名，如果您稍后删除分支，则会自动清理。这些多余的配置条目只会在分支存在时才存在，届时它们将被自动删除。

A downside to this approach is that you can only store one "note" per branch. Subsequent branch-note calls with an argument will overwrite the previous branch-note. You also don't get the benefit of storing the message in a trackable git object but maybe it will suffice for your purposes.

这种方法的一个缺点是每个分支只能存储一个“注释”。带有参数的后续分支注释调用将覆盖先前的分支注释。您也不会受益于将消息存储在可跟踪的 git 对象中，但也许它足以满足您的目的。

回答by Don Hatch

I like to make an empty commit whenever I create a new branch, with a commit message saying whatever needs to be said.

每当我创建一个新分支时，我都喜欢进行一次空提交，并带有一条提交消息，说明需要说什么。

git branch B A
git checkout B
git commit --allow-empty -m "Created branch 'B' from 'A'"

This also has a wonderful side effect of making the history shown in "git log --graph" much clearer-- namely it shows a clearly labelled fork in the tree at the time I created the branch, instead of what I'd normally get which is an unclear unlabelled fork at some later time when I happen to make my first commit while in B-- that kind of thing keeps me in a constant fog.

这也有一个很好的副作用，可以使“git log --graph”中显示的历史记录更加清晰——也就是说，它在我创建分支时在树中显示了一个清晰标记的分叉，而不是我通常会得到的当我在 B 中第一次提交时，这是一个不清楚的未标记的分叉——这种事情让我一直处于迷雾中。

回答by skiphoppy

The correct answer to this is now branch descriptions, a feature which was added to git after this question was originally asked.

对此的正确答案现在是分支描述，这是在最初提出此问题后添加到 git 的功能。

Here are two SO questions that come up with this answer: Branch descriptions in gitCan I add a message/note/comment when creating a new branch in Git?

以下是此答案中提出的两个 SO 问题： git 中的分支描述 在 Git 中创建新分支时，我可以添加消息/注释/评论吗？

回答by rkj

Using Brian's solution I've created git-note. You can use it like:

使用 Brian 的解决方案，我创建了git-note。你可以像这样使用它：

$ git note "Some note" # set note for current branch
$ git note -b branch # see note for branch
$ git note -l # list all the branches with theirs' notes

回答by MatrixFrog

You could just create a "tracking bug" in your issue tracker where you describe the big new feature in great detail, with mockups and UML diagrams and everything, and then name the branch bug1234.

您可以在问题跟踪器中创建一个“跟踪错误”，您可以在其中详细描述重要的新功能，包括模型和 UML 图以及所有内容，然后将分支命名为bug1234.

回答by Simon Richter

No. Notes are attached to specific commit IDs.

否。注释附加到特定的提交 ID。

回答by user5534993

Using git tag --annotatetags with descriptions may be created.

git tag --annotate可以创建使用带有描述的标签。

The tag is technically attributed to a commit instead of a branch. If all collaborators agree on using the branch name (as part of) the tag name, the corresponding tag(s) to a branch can be listedusing the branch name as part of a filter pattern. The -noption allows to show the actual annotation. Aliasesmay come handy in order to automatically use the current branch name for creating and listing special branch description tags.

该标签在技术上归因于提交而不是分支。如果所有协作者都同意使用分支名称（作为标签名称的一部分），则可以使用分支名称作为过滤器模式的一部分列出分支的相应标签。该-n选项允许显示实际注释。别名可能会派上用场，以便自动使用当前分支名称来创建和列出特殊的分支描述标签。

Note 1: git describemay be used to find the most recent tag in a branch. Unfortunately this may list tags of other branches if they are merged into the branch of interest.

注 1：git describe可用于查找分支中的最新标签。不幸的是，这可能会列出其他分支的标签，如果它们被合并到感兴趣的分支中。

Note 2: It is not recommendedto update a tag to HEADmanually using --force.

注2：这是不建议更新标签HEAD手动使用--force。

An advantage of using tags is that the description is available to all collaborators.

使用标签的一个优点是所有合作者都可以使用描述。