Git中的分支描述

Question

Git中是否有一种方式可以为分支添加“描述”？

虽然我尝试使用描述性名称，但是在单个分支上工作一段时间后，有时会减弱我对其他主题分支创建原因的记忆。我尽量使用描述性名称来命名分支，但我认为一个“描述”（关于分支目的的简短说明）会很好。

- Noufal Ibrahim

---

我之前也遇到过类似的问题。我使用该文件来记录分支及其存在的原因（以及其他内容）。 - themis

这将是一个非常有用的功能。git branch -a 可以在分支名称旁边显示描述。也许 git notes 将来会支持对分支和提交的注释？ - jhabbott

分支描述无法推送，因此它们相当无用，除非您想给自己发送消息。 - nurettin

@nurettin 是的，但我的请求是关于私人事务的。我只是想记住为什么我剪掉了这个分支。 - Noufal Ibrahim

Answer 1

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）使用的。请注意，它不适用于分离头分支。

该描述由脚本request-pull使用：参见提交c016814783和git merge --log。 request-pull是一个脚本，用于将两个提交之间的更改总结到标准输出中，并在生成的摘要中包含给定的URL。

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

- Greg Hewgill

---

目前我所知道的唯一方法是使用“git config branch.topic.description”命令来显示分支“topic”的描述信息，该信息存储在“.git/config”文件中。 - Greg Hewgill

谢谢。用一些别名来看待它其实不错。现在只要 git branch 能在列表中显示描述就好了... - Owen

目前，先前评论中引用的要点似乎不可用，但这个链接看起来相似：https://gist.github.com/carlosayam/5316969。 - pfalcon

很遗憾，你无法推送描述信息，因为它们存储在配置文件中，这使得团队协作时记录分支描述信息变得毫无意义。 - Achal Dave

很抱歉，@PedroRodrigues的代码片段链接已经失效。 - UpAndAdam

Answer 2

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

例如，在〜/ .gitconfig 下添加以下内容：

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

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

- tta

---

对我来说，$1变量不起作用 - 它什么也没有。我不知道为什么（我正在使用版本1.7.11-msysgit.1）。我改用$0，一切都好了。 - shytikov

@shytikov 对于使用参数的git别名，为了可移植性，我使用一个快速函数代替"sh -c"；例如，alias = "!f() { git checkout "${1}" && cat README.md; }; f"（在这种情况下，括号和引号不必要，只是为了完整起见，以防它们对于更复杂的内容有用）。 - michael

@michael_n，你的别名是一个bash别名还是一个git别名？ - UpAndAdam

唯一的问题是，如果您在检出时所在的文件夹中没有README文件，它会抱怨。 - UpAndAdam

@UpAndAdam 这是一个 git 别名，定义在 ~/.gitconfig 文件中的 [alias] 下面，而别名的名称实际上（并且令人困惑地）被称为我的实际配置中的 alias（我应该将其重命名为 cor 以保持一致）。我的实际 alias 别名是：alias = "!f() { git config --get-regexp "^alias.${1}$" ; }; f"。用法：git alias {alias_name} 或 git alias {alias_regexp}。类似于 bash 的 alias 命令，例如 $ alias ll 对我来说会产生 alias ll='ls -l'；而 $ git alias br 会产生 alias.br branch -v --list（也可以使用：$ git alias 'b.*'）。 - michael

Answer 3

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

图像如下，可以看到颜色：

- jsageryd

---

这与已接受的答案（发布超过一年）有何不同？ - Peter Mortensen

很不幸，你无法推送描述信息因为它们存储在你的配置文件中，这使得它对于团队中记录分支信息来说毫无意义。 - Peter Mortensen

Answer 4

README文件的建议者是Chris J，只要在.gitattribute中定义了一个自定义合并驱动器，它就可以工作。
这样，在合并期间，本地README版本将始终被保留。

"分支"的"描述"也称为与该元数据相关联的"注释"，但不受支持。

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

$ git show myBranch:README

如果你的README文件位于REPO的根目录，那么它将可以在任何路径下工作，因为git show所使用的路径是相对于该repo的顶级目录的绝对路径。

- VonC

---

如果想要实现这个，团队中的每个人都需要知道并在他们的 .gitattribute 文件中单独设置。如果是这样的话，我认为这将很难管理，并且实际执行的可能性很小。 - Don Hatch

@DonHatch：通常情况下，您会将.gitattributes文件提交到您的代码库中，因此不会出现问题。但是，当通过某些基于Web的界面合并时，例如在Azure DevOps中使用拉取请求时，这种方法似乎无法正常工作。 - Soren Bjornstad

Answer 5

这里有两个常见的建议：

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。

- Peter V. Mørch

---

可以将README文档放在主分支中。虽然这会增加混乱，但始终可以访问。 - Peter - Reinstate Monica

@PeterA.Schneider：当然可以，但是即使更改与主分支没有任何关系，添加新的分支也需要对主分支进行提交。此外，当从主分支创建分支时，所有分支都会有README的副本，这很混乱。 - Peter V. Mørch

我喜欢这个答案。简单而通用。 - Guildenstern

Answer 6

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

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

- Felicio

---

谢谢！我把它改成只查看我所在的分支-- "!describe() { git config branch.\"$(git symbolic-ref --short -q HEAD)\".description; }; describe"。请注意，我保持原文的意思和结构不变，并尽可能用通俗易懂的语言来翻译。 - aug

@aug - 我需要删掉参数引号前面的反斜杠才能使它正常工作：git config --global --add alias.about '!describe() { git config branch."$(git symbolic-ref --short -q HEAD)".description; }; describe' - Tom Tresansky

Answer 7

以下是翻译的结果：

这是一个 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 的回答，让我开始了解。

- Wayne

---

很好！它可以编译成shell或ohmyzsh吗？ - mqliutie

如果我们能够推送/拉取这些信息，那就更好了！没有办法做到吗？ - Paolo

Answer 8

假设你想创建一个分支

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

- AtlantaKid

---

这并不像一开始看起来那么有帮助，因为该注释附加在当前状态的分支上。如果您将新提交推送到分支，则“git show branch”不再显示该注释。 - John Gordon

Answer 9

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

- Owen

Answer 10

您可以将评论附加到标签：

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

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

- Jamey Hicks

---

这并不理想，因为它无法追踪分支的头部。 - AndyL

请检查注释：git tag -n - CoderLim