目前，Git 本身并没有内置的分支描述功能，开发者通常通过分支名来了解分支的目的，但这种方式不够直观。为了提升分支管理的清晰度和可读性，我在项目中引入了一个名为 .git/branch-notes 的本地文件，用于记录每个 Git 分支的描述信息。这个文件不会影响 Git 的版本控制功能，仅作为开发人员在本地维护分支说明的工具。
通过添加 git branch.note 命令，可以更方便地为当前分支添加描述，提高团队协作效率与代码可维护性。该命令对团队成员完全透明、易于使用，是对外展示的入口。
📌 一、用户应该如何配置
- 创建 .git/branch-notes 文件
在项目根目录下创建一个名为 .git/branch-notes 的普通文本文件，用于存储各分支的描述信息：
touch .git/branch-notes
或者你可以直接写入初始内容：
echo "| main | 主分支，用于生产环境代码" > .git/branch-notes
- 配置 Git 别名
将以下配置添加到你的 .gitconfig 文件中，使 git branch.note 命令正常工作：
⚠️ 注意：以下命令为 Mac OS 系统的配置文件。
[alias "branch"]
clear = "!f() { if test -f .git/branch-notes ; then grep -v $(git rev-parse --abbrev-ref HEAD) .git/branch-notes > .git/branch-notes.tmp && mv .git/branch-notes.tmp .git/branch-notes; fi;}; f"
add = "!f() { if [[ -n $1 ]]; then echo \"| $(git rev-parse --abbrev-ref HEAD) | $1 |\" >> .git/branch-notes ; fi; }; f"
show = "!f() { if test -f .git/branch-notes ; then grep --no-filename $(git rev-parse --abbrev-ref HEAD) .git/branch-notes | awk -F '|' '{print $3}'; else echo 'The file `.git/branch-notes` does not exist'; fi; }; f"
notes = "!f() { git branch --list | tr -d ' *' | while read -r name; do if [[ -n $(grep ${name} .git/branch-notes) ]]; then grep ${name} .git/branch-notes| sed 's/^|[[:space:]]//g' | awk -F '|' '{print $1 \"\\033[32m\" $2 \"\\033[0m\" }'; else echo $name; fi; done; }; f"
note = "!f() { if [[ -n $1 && $1 = '--add' && -n $2 ]]; then git branch.add $2; elif [[ -n $1 && $1 = '--clear' ]]; then git branch.clear; else git branch.show; fi; }; f"
✅ 所有分支描述操作均通过内部命令（如 branch.add、branch.show）实现，因此你只需配置 branch.note 命令即可。
📌 二、介绍一下 git branch.note 应该如何使用
- 添加分支描述
使用如下命令为当前分支添加描述（支持中文）：
git branch.note --add "用于开发用户登录模块，包含前端和后端接口"
💡 运行后，git branch.note 会自动将描述写入 .gitbranch 文件
- 查看当前分支的描述
直接使用以下命令查看当前分支的说明：
git branch.note
- 清空当前分支的描述
直接使用以下命令清空当前分支的说明：
git branch.note --clear
- 查看所有分支的描述
git branch.notes
三、 GIT 自带
只需在Git命令中使用git branch --edit-description命令后，Git会打开一个文本编辑器，供您编辑和添加分支描述
可以使用git branch --show-description命令来查看分支描述
参考：
