Git 中的分支描述

Branch descriptions in Git

提问by Noufal Ibrahim

Is there a way in Git to have a 'description' for branches?

Git 中有没有办法对分支进行“描述”？

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.

当我尝试使用描述性名称时，在单个分支上工作一段时间有时会抑制我对为什么创建其他一些主题分支的记忆。我尝试为分支使用描述性名称，但我认为“描述”（关于分支目的的简短说明）会很好。

采纳答案by Greg Hewgill

Git 1.7.9 supports this. From the 1.7.9 release notes:

Git 1.7.9 支持这一点。从1.7.9 发行说明：

 * "git branch --edit-description" can be used to add descriptive text
   to explain what a topic branch is about.

You can see that feature introduced back in September 2011, with commits 6f9a332, 739453a3, b7200e8:

您可以看到该功能于 2011 年 9 月推出，提交6f9a332、739453a3、b7200e8：

struct branch_desc_cb {
  const char *config_name;
  const char *value;
};

--edit-description::

Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. request-pull).

打开编辑器并编辑文本以解释分支的用途，以供各种其他命令使用（例如request-pull）。

Note that it won't work for a detached HEAD branch.

请注意，它不适用于分离的 HEAD 分支。

That description is used by the script request-pull: see commit c016814783, but also git merge --log.

该描述由脚本 request-pull 使用：请参阅提交 c016814783，但也git merge --log.

request-pullis a script used to summarizes the changes between two commits to the standard output, and includes the given URL in the generated summary.

request-pull是一个脚本，用于总结两次提交之间对标准输出的更改，并在生成的摘要中包含给定的 URL。

[From @AchalDave] Unfortunately, you can't push descriptions since they're stored in your config, making it useless for the sake of documenting branches in a team.

[来自@AchalDave] 不幸的是，您无法推送描述，因为它们存储在您的配置中，这对于记录团队中的分支来说毫无用处。

回答by tta

If you doend up using the README, create a git aliasmodifying git checkoutso that your README is displayed every time you switch branches.

如果你最终使用的自述中，创建一个git的别名修改git checkout，以便您的README显示每次转换分支的时间。

For example, add this in ~/.gitconfig, under [alias]

例如，在 ~/.gitconfig 中的[alias]下添加此内容

cor = !sh -c 'git checkout  && cat README' -

After this, you can run git cor <branch_name>to switch branch anddisplay the README of the branch you're switching to.

在此之后，您可以运行git cor <branch_name>切换分支并显示您要切换到的分支的自述文件。

回答by jsageryd

Use git branch --edit-descriptionto set or edit a branch description.

使用git branch --edit-description设置或编辑一个分支描述。

Here is a shell function to show branches similar to git branchbut with descriptions appended.

这是一个 shell 函数，用于显示类似于git branch但附加了描述的分支。

# Shows branches with descriptions
function gb() {
  current=$(git rev-parse --abbrev-ref HEAD)
  branches=$(git for-each-ref --format='%(refname)' refs/heads/ | sed 's|refs/heads/||')
  for branch in $branches; do
    desc=$(git config branch.$branch.description)
    if [ $branch == $current ]; then
      branch="* 3[0;32m$branch3[0m"
     else
       branch="  $branch"
     fi
     echo -e "$branch 3[0;36m$desc3[0m"
  done
}

Here is what gblooks like, shown here as text in case the image rots:

这是gb看起来的样子，在此处显示为文本，以防图像腐烂：

$ gb
* logging Log order details.  Waiting for clarification from business.
  master 
  sprocket Adding sprockets to the parts list.  Pending QA approval.

And as an image, so you can see the colors:

作为图像，您可以看到颜色：

回答by VonC

The READMEsuggested by Chris Jcan work, provided it is setup with a custom merge driver defined in a .gitattribute.
That way, the localversion of the READMEis always preserved during merges.

Chris J的README建议可以工作，前提是它使用. 这样，在合并期间始终保留的本地版本。.gitattribute
README

The "description" for branches is also know as a "comment" associated with that meta data, and it is not supported.

分支的“描述”也称为与该元数据关联的“评论”，它不受支持。

At least, with a READMEfile, you can, for any branch, do a:

至少，对于一个README文件，您可以对任何分支执行以下操作：

$ 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 showis an absolute one from the top directory of said repo.

如果你的自述文件在你的 REPO 的根目录下，它可以从任何路径工作，因为使用的路径git show是来自所述 repo 的顶级目录的绝对路径。

回答by Peter V. M?rch

There are two popular suggestions here:

这里有两个流行的建议：

1. git branch --edit-description: We don't like this because you can't push it. Maybe I can remember what the branches I created do, but my team sure can't.
2. READMEfile pr. branch. This is a pain during merges: Super-prone to merge conflicts and we'll be pulling in READMEfrom branches when we merge feature branches. Diffs between branches are also a pain.

1. git branch --edit-description: 我们不喜欢这个，因为你不能推动它。也许我能记住我创建的分支是做什么的，但我的团队肯定不能。
2. README文件公关 分支。这是合并过程中的一个痛苦：超级容易合并冲突，README当我们合并功能分支时，我们将从分支中拉进来。分支之间的差异也是一种痛苦。

We've decided to create an orphan branches-readmebranch. Orphan branches are branches with their own separate history - you may know them from Github's gh-pagesbranches. This orphan branch contains a single READMEfile. It has contents like:

我们决定创建一个孤儿branches-readme分支。孤儿分支是有自己独立历史的gh-pages分支——你可能从 Github 的分支中知道它们。这个孤立分支包含一个README文件。它有如下内容：

master:
    The default branch
mojolicious:
    Start using Mojolicious
branch-whatever:
    Description of the whatever branch

It is push-able and merge-friendly. View the READMEfrom any branch with:

它是可推送和合并友好的。README从任何分支查看：

git show branches-readme:README

Disadvantages are that you need to checkout the weird orphan branch when you want to update the READMEand the READMEdoesn't auto-update as branches get renamed, come or go. That is fine for us, though.

缺点是当你想要更新时需要检出奇怪的孤立分支，README并且README当分支被重命名、来或去时不会自动更新。不过，这对我们来说很好。

Do it like:

这样做：

git checkout --orphan branches-readme
# All the files from the old branch are marked for addition - skip that
git reset --hard
# There are no files yet - an empty branch
ls
vi README
# put in contents similar to above
git add README
git commit -m "Initial description of the branches we already have"
git push origin branches-readme
# get all your original files back
git checkout master

Similary, individual team members can also create their own branches-$userorphan branches describing their own private branches if they want to, as long as they don't push them to the team.

类似地，branches-$user如果愿意，单个团队成员也可以创建自己的 孤儿分支来描述他们自己的私有分支，只要他们不将它们推送到团队中即可。

With further tooling this could also be integrated with the output of git branch. To that end, perhaps a README.yamlfile could be considered instead of a plain README.

通过进一步的工具，这也可以与git branch. 为此，也许README.yaml可以考虑使用文件而不是普通的README.

回答by Felicio

git config --global --add alias.about '!describe() { git config branch."".description; }; describe'

Command will define a global option alias.aboutas shell expression. Running git about <branch>in a repository will display branch's description if set.

命令将定义一个全局选项alias.about作为 shell 表达式。git about <branch>如果设置，在存储库中运行将显示分支的描述。

回答by Owen

Here's a possible implementation of the git branchescommand Greg Hewgill alluded to:

这是git branchesGreg Hewgill 提到的命令的可能实现：

#!/usr/bin/perl

sub clean {
    map { s/^[\s\*]*\s// } @_;
    map { s/\s*$// } @_;
    return @_;
}

sub descr {
    $_ = `git config branch.@_.description`;
    s/\s*$//;
    return $_;
};
sub indent {
    $_ = shift;
    s/^/      /mg;
    return $_;
};

my @branches = clean `git branch --color=never --list`;
my %merged = map { $_ => 1 } clean `git branch --color=never --merged`;

for my $branch (@branches) {
    my $asis = `git branch --list --color=always $branch`;
    $asis =~ s/\s*$//;
    print "  $asis";
    print " 3[33m(merged)3[0m" if ($merged{$branch} and $branch ne "master");
    print "\n";

    print indent descr $branch;
    print "\n";
    print "\n";
}

回答by Wayne

Here's a gitaliasthat lets you both set and read descriptions on the current branch:

这是一个gitalias允许您在当前分支上设置和读取描述的代码：

git config --global --add alias.about '!describe() { msg=""; 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.

特别感谢@Felicio 的回答让我开始了。

回答by Jamey Hicks

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.

按照惯例，您可以拥有与分支名称相关的标签，或者您可以使用 tag -f 将注释标签保留在主题分支的开头。

回答by AtlantaKid

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