Git中的分支描述

Git中有没有一种方法可以对分支机构进行“描述”？

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

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

 *“ 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。

[From @AchalDave]不幸的是，由于描述已存储在您的配置中，因此您无法推送描述，这对于记录团队中的分支无用。

如果确实使用了README，请创建一个git别名修改，git checkout以便每次切换分支时都显示README。

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

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

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

使用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.

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

Chris J的README建议可以使用，只要它使用在中定义的自定义合并驱动程序进行设置即可。 这样，在合并过程中始终会保留的本地版本。.gitattribute
README

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

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

$ git show myBranch:README

如果自述文件位于REPO的根目录下，则它将在任何路径下工作，因为所使用的路径git show是该仓库顶部目录中的绝对路径。

这里有两个流行的建议：

1. git branch --edit-description：我们不喜欢这样，因为您不能推动它。也许我记得我创建的分支机构做什么，但是我的团队肯定不会。
2. README文件 科。这在合并时很痛苦：合并冲突极易发生，README当我们合并要素分支时，我们将从分支中退出。分支之间的差异也是一种痛苦。

我们决定创建一个孤立branches-readme分支。孤儿分支是具有各自独立历史的gh-pages分支-您可能从Github的分支中知道它们。此孤立分支包含一个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。

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

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

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

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

这是一个git alias允许您设置和阅读当前分支上的描述的方法：

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为我提供的答案。

您可以在标签上附加注释：

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

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

假设您要创建一个分支

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

我很确定当前不支持该功能。我认为您最好的选择是在具有所需信息的分支中创建一个描述文本文件（基本上是README）。

选择的答案对我来说似乎太过分了。我倾向于保持每个分支的描述文件，该文件是一个正常的源控制下的文件，比如master.txt，dev.txt等，如果有一个笨拙的数量或分支机构我想创建一个层次结构，以更好地组织它。

只需使用：

git config branch.<branch name>.description

要在应得的信用额度上给予信用：https : //glebbahmutov.com/blog/git-branches-with-descriptions/

采用

git branch --list -v

显示上游分支：

git branch --list -vv

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