Git分支描述管理：基于.ruanyf/weekly项目的.git/branch-notes本地分支说明工具及git branch.note命令使用指南

背景说明

目前，Git 本身并没有内置的分支描述功能，开发者一般通过分支名来了解分支的目的，但这种方式不够直观。

为了提升分支管理的清晰度和可读性，我在项目中引入了一个名为 .git/branch-notes 的本地文件，用于记录每个 Git 分支的描述信息。这个文件不会影响 Git 的版本控制功能，仅作为开发人员在本地维护分支说明的工具。

通过添加 git branch.note 命令，可以更方便地为当前分支添加描述，提高团队协作效率与代码可维护性。该命令对团队成员完全透明、易于使用，是对外展示的入口。

一、 配置 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"

📌 二、 git branch.note 应该如何使用

1. 为当前分支 添加分支描述

使用如下命令为当前分支添加描述：

git branch.note --add "第三方登录"

💡 运行后，git branch.note 会自动将描述写入 .git/branch-notes 文件，格式如下：

| <branch-name> | <description> |

2. 查看当前分支的描述

直接使用以下命令查看当前分支的说明：

git branch.note

📝 此命令会自动读取 .git/branch-notes 文件中的内容，并输出当前分支的描述。如果没有设置描述，则会显示空白。

3. 查看所有分支的描述

直接使用以下命令查看当前分支的说明：

git branch.notes

列出所有分支并展示出分支的描述

feat/oAuth 第三方登录
feat/package-switching 套餐切换
feat/stat-maas  大模型数据统计

原文地址