Git 中的分支描述

Question

Git 中有没有办法为分支提供“描述”？

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

Answer 1

我很确定当前不支持该功能。我认为你最好的选择是在包含你想要的信息的分支中创建一个描述文本文件，基本上是一个 README。

Answer 2

Chris J 建议的 README 可以工作，前提是使用 custom merge driver defined in a .gitattribute 进行设置。
这样一来，README 的本地 版本在合并过程中始终被保留。

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

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

$ git show myBranch:README

如果您的 README 位于您的 REPO 的根目录，它可以从任何路径运行，因为 git show 使用的路径是来自该 repo 顶级目录的绝对路径。

Answer 3

选择的答案对我来说似乎有点过头了。我倾向于维护一个每个分支描述文件，它是一个正常的源代码控制文件，比如master.txt、dev.txt 等，如果有一个笨拙的数字或分支，我会创建一个层次结构来更好地组织它.

Answer 4

您可以将 cmets 附加到标签：

git tag -m 'this was a very good commit' tag1

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

Answer 5

如果您确实最终使用了 README，请创建一个 git alias 修改 git checkout，以便每次切换分支时都会显示您的 README。

例如，将其添加到 ~/.gitconfig 中的 [alias]

下

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

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

Answer 6

Git 1.7.9 支持这一点。来自1.7.9 release notes：

* "git branch --edit-description" 可用于添加描述性文本 解释一个主题分支是关于什么的。

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

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

--edit-description::

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

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

脚本 request-pull 使用该描述：请参阅 commit c016814783，但也可参阅 git merge --log。

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

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

Answer 7

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

#!/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 " \033[33m(merged)\033[0m" if ($merged{$branch} and $branch ne "master");
    print "\n";

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

Answer 8

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

这是一个 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="* \033[0;32m$branch\033[0m"
     else
       branch="  $branch"
     fi
     echo -e "$branch \033[0;36m$desc\033[0m"
  done
}

这是gb 的样子，这里显示为文本以防图像腐烂：

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

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

Answer 9

使用

git branch --list -v

显示上游分支：

git branch --list -vv

添加-r 以仅显示远程或-a 以显示远程和本地。

Answer 10

这里有两个流行的建议：

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

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

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

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

git show branches-readme:README

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

这样做：

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

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

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

Answer 11

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

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

Answer 12

只需使用：

git config branch.<branch name>.description

在信用到期时给予信用： https://glebbahmutov.com/blog/git-branches-with-descriptions/

Answer 13

这是一个gitalias，可以让你设置和阅读当前分支的描述：

git config --global --add alias.about '!describe() { msg="$1"; git config branch."$(git rev-parse --abbrev-ref HEAD)".description ${msg:+"$msg"}; }; describe'

用法/示例：

(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

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

Answer 14

假设你要创建一个分支

git branch branch-20200328
git notes add branch-20200328 -m "This branch is for whatever"
git notes show branch-20200328

Answer 15

你可以使用

git config --get-regexp "branch.*.description"