Git中的分支描述

我非常确定目前不支持该特性。我认为最好的办法是创建一个描述文本文件，基本上是一个README，在包含您想要的信息的分支中。

由克里斯·J建议的README可以工作，只要它是用自定义合并驱动程序定义在.gitattribute设置的 这样，在合并期间，README的当地的版本总是被保留

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

至少，对于README文件，你可以对任何分支执行:

$ git show myBranch:README

如果你的README在你的REPO的根目录，它将从任何路径工作，因为git show使用的路径是绝对的一个从REPO的顶部目录。

选定的答案对我来说似乎太夸张了。我倾向于维护一个每个分支的描述文件，这是一个正常的源代码控制文件，比如master.txt， dev.txt等，如果有一个难以处理的数字或分支，我会创建一个层次结构来更好地组织它。

你可以给标签添加注释:

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

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

如果你做最终使用README，创建一个修改git checkout的git别名，这样你的README在每次切换分支时都会显示出来。

例如，在~/中添加这个。(别名)下

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

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

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.

你可以看到该特性早在2011年9月就引入了，通过提交6 f9a332， 739453 a3， b7200e8:

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


--edit-description::

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

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

该描述被脚本request-pull使用:请参见提交c016814783，也请参见git merge --log。

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

不幸的是，你不能推送描述，因为它们存储在你的配置中，这对于团队中的分支来说是无用的。

下面是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";
}

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

作为一个图像，你可以看到颜色:

使用

git branch --list -v

显示上游分支:

git branch --list -vv

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

这里有两个流行的建议:

1. git branch --edit-description:我们不喜欢这个，因为你不能推它。也许我能记住我创建的分支是做什么的，但我的团队肯定不能。
2. README文件pr. branch。这是合并过程中的一个痛苦:超级容易合并冲突，当我们合并特性分支时，我们将从分支中拉入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文件。

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

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

只使用:

git config branch.<branch name>.description

下面是一个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 branch branch-20200328
git notes add branch-20200328 -m "This branch is for whatever"
git notes show branch-20200328

你可以使用

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

关于格雷格Hewgill的2012 回答, Git 1.7.9 (2012 Q1)还包含了一些对git branch --edit-description的检查:

参见提交c2d17ba (05 Feb 2012) by juno C Hamano (gitster)。
^{(由Junio C Hamano—gitster—在提交d88698e中合并，10 Feb 2012)}

branch --edit-description:防止输入错误的分支名称

在编辑分支描述时，很容易键入错误的分支名称，例如:

$ git checkout -b my-topic master
: work work work
: now we are at a good point to switch working something else
$ git checkout master
: ah, let's write it down before we forget what we were doing
$ git branch --edit-description my-tpoic

命令不注意到分支my- topic不存在。
它不会丢失(它会成为未出生的my- topic分支的描述)，但不是很有用。
因此，要发现这样的情况并找出错误，以减少这种常见错误的悲伤因素

顺便说一句，当HEAD指向一个未出生的分支(紧跟在“__abc1”之后，或“__abc2”之后)时，也会错误地输出--edit-description，因为在这一点上，你甚至没有任何提交，这是你的历史记录的一部分，没有必要描述这个特定的分支与它所分叉的分支有什么不同，而这正是分支描述设计用来捕获的有用信息。

我们可能想在以后对未出现的情况进行特殊处理，但这超出了这个补丁的范围，以防止在1.7.9系列得到广泛使用之前出现更多常见的错误。

虽然格雷格Hewgill的2012 回答是准确的，但使用git branch --edit-description会导致:

fatal: could not unset 'branch.main.description'

GIT_EDITOR=: git branch --edit-description^(man)导致失败，已在Git 2.39 (Q4 2022)中更正。

参见提交e288b3d (30 Sep 2022) by juno C Hamano (gitster)。
^{(由Junio C Hamano—gitster—在提交272年be0d中合并，17 Oct 2022)}

branch:不会失败一个无操作--edit-desc

想象一下，在一个没有分支描述的分支上运行“git branch --edit-description"^(man)”，然后在清空编辑缓冲区后退出编辑器，这是告诉命令你改变了主意，你根本不想要描述的方式。

该命令应该愉快地执行，不为当前分支添加分支描述，并成功退出。
但是它没有这样做:

$ git init -b main
$ git commit --allow-empty -m commit
$ GIT_EDITOR=: git branch --edit-description
fatal: could not unset 'branch.main.description'

最终结果是OK的，因为在生成的存储库中不存在配置变量，但是我们应该做得更好。
如果我们知道我们没有描述，如果编辑器要求我们不要有描述，我们可以什么都不做返回

这当然介绍了tocou。

(检查时间到使用时间( tocou ):由竞态条件引起的一类软件错误，该竞态条件涉及对系统部分状态的检查(如安全凭据)以及检查结果的使用。)

如果您从另一个窗口向同一个分支添加了一个分支描述，而您打开了编辑器来编辑该描述，然后不写任何东西就退出了编辑器，那么我们最终不会删除您在另一个窗口中添加的描述。
但是在这一点上，您是在愚弄自己的存储库，如果这很痛苦，您最好不要这样做;-).

还有:未出生的分支上的“git branch --edit-description"^(man)”误导性地说不存在这样的分支，这已在Git 2.39 (Q4 2022)中更正。

参见提交bcfc82b (08 Oct 2022) by Rubén Justo (rjusto)。
^{(由Junio C Hamano—gitster—在提交4050354中合并，17 Oct 2022)}

branch:对不存在的分支错误的描述

^{署名:Rubén Justo}

当存储库还没有提交时，一些错误描述没有分支:

$ git init -b first


$ git branch --edit-description first
error: No branch named 'first'.


$ git branch --set-upstream-to=upstream
fatal: branch 'first' does not exist


$ git branch -c second
error: refname refs/heads/first not found
fatal: Branch copy failed

,“至上”;布兰奇是未出生的，但说它不存在是令人困惑的。

选择“-c"(副本)和"-m"(rename)显示相同的错误时，原点分支不存在:

$ git branch -c non-existent-branch second
error: refname refs/heads/non-existent-branch not found
fatal: Branch copy failed


$ git branch -m non-existent-branch second
error: refname refs/heads/non-existent-branch not found
fatal: Branch rename failed

注意"--edit-description"如果没有显式参数，则已经在错误中考虑了空库情况。
还要注意&;-m"在初始分支上，它是允许的操作

使那些未出生或不存在分支的分支操作的错误描述更有信息。

更改的结果如下:

$ git init -b first


$ git branch --edit-description first
error: No commit on branch 'first' yet.


$ git branch --set-upstream-to=upstream
fatal: No commit on branch 'first' yet.


$ git branch -c second
fatal: No commit on branch 'first' yet.


$ git branch [-c/-m] non-existent-branch second
fatal: No branch named 'non-existent-branch'.

在Git 2.39 (Q4 2022)中，“git branch --edit-description @{-1}"^(man)”现在是一种在切换到当前分支之前编辑分支描述的方法。

参见提交0 dc4e5c (11 Oct 2022) by Rubén Justo (rjusto)。
^{(由Junio C Hamano—gitster—在提交c2058ea中合并，21 Oct 2022)}

branch:支持像@{-1}这样的快捷方式，已完成

^{署名:Rubén Justo}

分支命令选项&;edit-description&;， &;set-upstream-to"和“;unset-upstream"期望一个分支名称。
由于ae5a6c3 (checkout: implementation "@{-N}"第n个分支的快捷方式名称，2009-01-17,Git v1.6.2-rc0——合并)，一个分支可以使用像@{-1}这样的快捷方式指定。
在考虑参数时，需要解决这些快捷方式

我们可以修改之前签出分支的描述:

 $ git branch --edit--description @{-1}

我们可以修改之前签出分支的上游:

 $ git branch --set-upstream-to upstream @{-1}
$ git branch --unset-upstream @{-1}