寫在最前面的使用方式

1. 查看 所有分支的備注
   git branch.notes
2. 創建分支并為分支添加備注
   git co -b feat/oauth -m '第三方用戶登錄'
3. 對分支描述的添加與清除
   添加 git branch.note --add 清除 git branch.note --clear

📝 為 Git branch 命令添加描述功能

🧭 背景說明

目前，Git 本身并沒有內置的分支描述功能，開發者通常通過分支名來了解分支的目的，但這種方式不夠直觀。為了提升分支管理的清晰度和可讀性，我在項目中引入了一個名為 .gitbranch 的本地文件，用于記錄每個 Git 分支的描述信息。這個文件不會影響 Git 的版本控制功能，僅作為開發人員在本地維護分支說明的工具。

通過添加 git branch.note 命令，可以更方便地為當前分支添加描述，提高團隊協作效率與代碼可維護性。該命令對團隊成員完全透明、易于使用，是對外展示的入口。

---

📌 一、用戶應該如何配置

1. 創建 .gitbranch 文件

在項目根目錄下創建一個名為 .gitbranch 的普通文本文件，用于存儲各分支的描述信息：

touch .gitbranch

或者你可以直接寫入初始內容：

echo "| main | 主分支，用于生產環境代碼" > .gitbranch

📌 推薦將 .gitbranch 寫入到 .gitignore 中 echo .gitbranch >> .gitignore ， 要不然切換分支時它也會跟隨變更。

2. 配置 Git 別名

將以下配置添加到你的 .gitconfig 文件中，使 git branch.note 命令正常工作：

?? 注意：以下命令為 Mac OS 系統的配置文件。

[alias "branch"]clear = "!f() { if test -f .gitbranch ; then grep -v $(git rev-parse --abbrev-ref HEAD) .gitbranch > .gitbranch.tmp && mv .gitbranch.tmp .gitbranch; fi;}; f"add =  "!f() { if [[ -n $1 ]]; then echo \"| $(git rev-parse --abbrev-ref HEAD) | $1 |\" >> .gitbranch ; fi; }; f"show = "!f() { if test -f .gitbranch ; then grep --no-filename $(git rev-parse --abbrev-ref HEAD) .gitbranch | awk -F '|' '{print $3}'; else echo 'The file `.gitbranch` does not exist'; fi; }; 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"notes = "!f() { git branch --list | tr -d ' *' | while read -r name; do if [[ -n $(grep ${name} .gitbranch) ]]; then grep ${name} .gitbranch| sed 's/^|[[:space:]]//g' | awk -F '|' '{print \"\\033[32m\" $1 $2 \"\\033[0m\" }'; else echo  $name; fi; done; }; f"

? 所有分支描述操作均通過內部命令（如 branch.add、branch.show）實現，因此你只需配置 branch.note 命令即可。

---

📌 二、介紹一下 git branch.note 應該如何使用

1. 添加分支描述

使用如下命令為當前分支添加描述（支持中文）：

git branch.note --add "這是當前分支的說明"

? 示例：

git branch.note --add "用于開發用戶登錄模塊，包含前端和后端接口"

💡 運行后，git branch.note 會自動將描述寫入 .gitbranch 文件，格式如下：

| <branch-name> | <description> |

例如：執行 git branch.note

用于開發用戶登錄模塊，包含前端和后端接口

2. 查看當前分支的描述

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

git branch.note

? 示例：

git branch.note

📝 此命令會自動讀取 .gitbranch 文件中的內容，并輸出當前分支的描述。如果沒有設置描述，則會顯示空白。

3. 清空當前分支的描述

直接使用以下命令清空當前分支的說明：

git branch.note --clear

當前分支的描述將會被清空 ?? 請謹慎操作

4. 查看所有分支的描述

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

git branch.notes

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

eat/cus-register
feat/data-statistics
feat/oAuth
feat/package-switching 這是項目的描述
feat/replace-get-api-list
feat/stat-maas
feat/super-group
feat/test-template
fix/blog
fix/config-base
fix/huoshan-register
fix/optimization

快速創建分支 并 添加分支描述

文件名 git-co

請將 git-co 文件添加到 $PATH 中；

#!/bin/bash# git-co - 自定義 Git 插件，用于處理帶 -m 參數的 checkout 命令
# 使用方法：git co [checkout 參數] -m [注釋內容]# 初始化變量
note_message=""
checkout_args=()
found_m=false# 解析命令行參數
for arg in "$@"; doif [[ $found_m == true ]]; thennote_message="$arg"found_m=falseelif [[ $arg == "-m" ]]; thenfound_m=trueelsecheckout_args+=("$arg")fi
done# 檢查是否找到了 -m 參數但沒有提供值
if [[ $found_m == true ]]; thenecho "錯誤：-m 選項需要一個參數值。" >&2exit 1
fi# 執行 git checkout 命令
git checkout "${checkout_args[@]}"
checkout_status=$?# 如果 checkout 成功且有注釋內容，則添加分支注釋
if [[ $checkout_status -eq 0 && -n "$note_message" ]]; then# 獲取當前分支名current_branch=$(git rev-parse --abbrev-ref HEAD)if [[ -n "$current_branch" ]]; thengit branch.add $note_message;fi
fiexit $checkout_status

使用方式

如 git co -b feat/test -m '這是一個分支的描述'

原文地址 git branch 分支描述