1. 项目概述：告别“提交信息焦虑”，让AI成为你的Git搭档

每次敲完代码，面对那个空荡荡的 git commit -m 输入框，是不是都得愣上几秒，甚至几分钟？是该写“修复了一个小bug”，还是“优化了用户登录逻辑”？写得太简单，日后回溯时一头雾水；想写详细点，又觉得词穷且浪费时间。这几乎是每个开发者，无论新手还是老手，都经历过的“提交信息焦虑”。今天分享的，就是我用一个简单的Bash脚本，结合本地运行的AI模型，彻底解决这个痛点的实战方案。

这个方案的核心思路非常直接： 让AI来阅读你的代码变更，并为你生成专业、清晰的提交信息建议 。它不是一个复杂的云端服务，而是一个完全运行在你本地的自动化工具链。你只需要在终端里敲一个自定义命令，脚本就会自动暂存所有更改，调用本地AI模型分析变更内容，生成建议信息，并允许你快速编辑或直接使用，最后完成提交和推送。整个过程，你将从繁琐的思考中解放出来，把精力完全集中在代码本身。

这套流程特别适合日常开发节奏快、需要频繁提交的开发者，或者团队希望统一提交信息规范但执行起来总有偏差的场景。它基于 Ollama 这个可以本地运行大模型的工具，确保了代码隐私（你的变更不会上传到任何第三方服务器），同时利用 phi3.5 这类轻量级但足够聪明的模型，生成质量远超“fixed stuff”的提交信息。接下来，我会详细拆解从环境准备、脚本原理到每一步实操的完整过程，并附上我踩过坑后总结的优化技巧。

2. 核心工具选型与原理剖析

在动手之前，理解我们选择的工具及其背后的工作原理至关重要。这能帮助你在遇到问题时快速排查，也能根据自身需求进行灵活调整。

2.1 为什么选择 Ollama 与 Phi-3.5-mini？

Ollama 是一个开源项目，它极大地简化了在本地运行大型语言模型（LLM）的过程。你不需要关心复杂的模型部署、依赖库冲突或者GPU配置（当然，有GPU会更快），一条命令就能拉取和运行模型。它提供了统一的REST API和命令行接口（CLI），使得像我们这样的脚本可以非常方便地与之交互。

选择它，首要考虑的是 隐私与可控性 。你的代码变更（ git diff 的输出）是核心的智力财产和可能的敏感信息。使用ChatGPT等云端API虽然方便，但意味着你需要将代码片段发送到外部服务器。对于公司项目或个人私有项目，这存在安全合规风险。Ollama让一切都在你的机器上完成，从根本上杜绝了数据泄露的可能。

其次，是 离线可用性与成本 。一旦模型下载完成，你可以完全离线使用，不受网络波动影响，也没有持续的API调用费用。这对于网络环境不稳定或希望严格控制成本的开发者来说是个福音。

为什么是 Phi-3.5-mini？ 在项目初期，我尝试过几个不同的模型。

• Llama 3 8B/7B ：能力很强，生成的提交信息非常专业，但模型体积较大（约4-5GB），在只有CPU的机器上推理速度较慢（一次生成可能需要10-20秒），对于追求“秒级”响应的提交体验来说，等待感明显。
• Gemma 2B ：非常轻快，但有时生成的描述过于简略或偶尔偏离代码变更的核心。
• Phi-3.5-mini (3.8B) ：这是微软推出的一个“小巨人”。它在3.8B的参数规模下，展现了接近7B-8B模型的理解和推理能力。经过实测，它对于代码变更的理解准确度很高，生成的提交信息格式规范、要点清晰，而且推理速度极快（在16GB内存的MacBook Air M1上，约2-3秒即可完成）。在效果、速度和资源消耗之间取得了完美的平衡，因此成为了我的首选。

注意 ：模型选择是动态的。Ollama的模型库在不断更新，你可以随时通过 ollama list 查看已安装的模型，并通过 ollama run 来测试新模型的效果。找到最适合你机器性能和需求的那一个。

2.2 Bash脚本：胶水与自动化引擎

Bash脚本在这里扮演着“胶水”和“自动化引擎”的角色。它的任务流程清晰：

1. 环境检查 ：确认当前目录是一个Git仓库，并且有未提交的更改。避免在非仓库目录误操作或无变更时生成无意义的提交。
2. 变更捕获 ：使用 git add . 暂存所有变更，并通过 git diff --cached --name-only 获取已暂存文件的列表。这里有一个关键点：我们分析的是 --cached （已暂存）的差异，而不是工作区的差异。这确保了AI分析的对象就是你即将提交的内容，准确无误。
3. AI交互 ：将变更文件列表作为提示词（Prompt）的一部分，通过 ollama run 命令发送给Phi-3.5-mini模型，请求它生成提交信息。
4. 人机交互 ：将AI生成的建议展示给用户，并提供编辑机会。这是自动化和人工控制的结合点，保证了最终提交信息的质量完全由开发者把关。
5. 执行提交 ：使用用户确认或编辑后的信息，执行 git commit 和 git push 。

这个脚本的精妙之处在于，它用不到50行的代码，串联起了Git操作、AI推理和用户交互，形成了一个完整的、可重复的工作流闭环。

2.3 关于Windows环境的特别说明

原文提到了Git Bash。在Windows上，Git Bash提供了一个非常接近Linux的Bash环境，使得我们的脚本可以几乎无缝运行。但有几个Windows特有的点需要注意：

• 路径格式 ：在脚本中引用路径时，尽量使用Unix风格的 / ，Git Bash会自动处理。但在配置 PATH 时， ~ （家目录）在Git Bash中对应的是 C:\Users\你的用户名 。
• Ollama安装 ：请务必从Ollama官网下载Windows版本的安装程序。安装后，Ollama服务会以后台形式运行，并且在Git Bash中可以直接调用 ollama 命令。
• 文件权限 ： chmod +x 命令在Git Bash和Windows NTFS文件系统上依然有效，它会标记文件为可执行。这与Linux的文件权限机制虽不完全相同，但足以让Bash识别该脚本为可执行文件。

3. 从零开始：详细配置与实操步骤

让我们一步步搭建起这个自动化工作流。请跟随操作，并注意我穿插其中的“实操心得”。

3.1 基础环境准备

首先，确保你的系统上已经安装了以下两个核心工具：

1. Git ：这应该是开发者的标配。前往 Git 官网 下载并安装。安装时，记得勾选“将Git添加到系统PATH环境变量”的选项，这样才能在任意终端使用git命令。
2. Ollama ：前往 Ollama 官网 下载对应你操作系统（Windows/macOS/Linux）的安装包。安装过程非常简单，一路下一步即可。

安装完成后，打开你的终端（Windows用Git Bash或Windows Terminal，macOS用Terminal，Linux用你喜欢的Shell）。

验证安装：

git --version
ollama --version

两条命令都应成功输出版本号。

3.2 拉取并验证Phi-3.5-mini模型

Ollama安装后，我们需要拉取Phi-3.5-mini模型。在终端中执行：

ollama pull phi3.5:mini

这个命令会从Ollama的模型库中下载 phi3.5:mini 这个特定标签的模型。下载速度取决于你的网络。完成后，可以通过以下命令进行一个简单的交互测试，确保模型工作正常：

ollama run phi3.5:mini "Hello, write a short git commit message for adding a new feature."

如果模型能回应一段关于添加新功能的提交信息，说明环境就绪。

实操心得 ： phi3.5 是模型系列名， mini 是它的一个版本标签。直接使用 ollama pull phi3.5 可能会拉取默认版本（有时是较大的版本）。明确指定 :mini 能确保我们获取到最合适的轻量版。你可以通过 ollama list 查看所有已安装的模型及其标签。

3.3 创建并优化自动化脚本

接下来是核心——创建我们的Bash脚本。我将在原文脚本基础上，分享几个增强稳定性和用户体验的优化点。

使用你喜欢的文本编辑器（如VS Code, Sublime Text, 甚至 nano / vim ），创建一个新文件，命名为 git_auto_commit.sh 。

将以下优化后的脚本内容复制进去：

#!/bin/bash

# git_auto_commit.sh - 使用本地AI生成Git提交信息
# 作者：你的名字
# 版本：1.1

# 颜色定义，用于美化输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# 函数：打印带颜色的信息
info() { echo -e "${BLUE}[INFO]${NC} $1"; }
success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }

# 1. 检查当前目录是否为Git仓库
if ! git rev-parse --git-dir > /dev/null 2>&1 ; then
    error "当前目录不是一个Git仓库。请确保在正确的项目目录下运行此脚本。"
    exit 1
fi

# 2. 检查是否有未暂存的更改
if [ -z "$(git status --porcelain)" ]; then
    info "工作区是干净的，没有检测到任何更改。脚本退出。"
    exit 0
fi

# 3. 获取当前分支名，用于推送
CURRENT_BRANCH=$(git branch --show-current)
info "当前工作分支: $CURRENT_BRANCH"

# 4. 交互式暂存更改
echo "检测到以下更改："
git status --short

read -p "是否暂存所有更改？(y/n, 默认y): " -n 1 -r STAGE_ALL
echo
if [[ $STAGE_ALL =~ ^[Nn]$ ]]; then
    info "请使用 'git add <file>...' 手动暂存你需要的文件，然后重新运行此脚本。"
    exit 0
else
    info "正在暂存所有更改..."
    git add .
fi

# 5. 获取已暂存文件的差异摘要
# 我们获取文件名和简短的diffstat，为AI提供更丰富的上下文
CHANGED_FILES=$(git diff --cached --name-only | tr '\n' ', ' | sed 's/, $//')
DIFF_STAT=$(git diff --cached --stat)
info "已暂存文件: $CHANGED_FILES"

# 6. 调用Ollama生成提交信息建议
info "正在请求Phi-3.5-mini分析变更并生成提交信息..."
# 构建更清晰的Prompt
PROMPT="你是一个资深的软件开发工程师，擅长编写清晰、规范的Git提交信息。
请根据以下代码变更摘要，生成一条简洁、专业、信息丰富的提交信息。
要求：
1. 使用祈使语气开头（例如：'Fix', 'Add', 'Update', 'Refactor'）。
2. 第一行是简短摘要（不超过50字符）。
3. 空一行后，写一段更详细的描述（可选，说明变更原因和影响）。
4. 如果相关，可以列出关键更改点。

以下是本次提交的变更摘要：
--- 变更文件 ---
${CHANGED_FILES}
--- 变更统计 ---
${DIFF_STAT}
--- 结束 ---

请只输出最终的提交信息内容，不要有其他任何解释或前缀。"

SUGGESTED_MSG=$(ollama run phi3.5:mini "$PROMPT")

if [ -z "$SUGGESTED_MSG" ] || [[ "$SUGGESTED_MSG" =~ ^[[:space:]]*$ ]]; then
    warning "AI未能生成有效的提交信息。将使用备用信息。"
    SUGGESTED_MSG="Update: $(date '+%Y-%m-%d %H:%M:%S')"
else
    success "AI生成建议成功！"
fi

echo -e "\n${YELLOW}=== AI建议的提交信息 ===${NC}"
echo "$SUGGESTED_MSG"
echo -e "${YELLOW}=== 结束 ===${NC}\n"

# 7. 用户确认或编辑
read -p "是否使用以上信息提交？(y:使用, n:手动输入, e:编辑建议): " -n 1 -r CHOICE
echo

case $CHOICE in
    [Yy]* )
        FINAL_MSG="$SUGGESTED_MSG"
        ;;
    [Ee]* )
        echo "请在编辑器中修改建议信息。完成后保存并关闭编辑器。"
        # 将建议信息写入临时文件供编辑
        TEMP_FILE=$(mktemp)
        echo "$SUGGESTED_MSG" > "$TEMP_FILE"
        ${EDITOR:-vi} "$TEMP_FILE"
        FINAL_MSG=$(cat "$TEMP_FILE")
        rm "$TEMP_FILE"
        ;;
    * )
        echo "请输入你的提交信息（支持多行，以单独一行的 . 结束输入）："
        FINAL_MSG=""
        while IFS= read -r line; do
            if [ "$line" = "." ]; then
                break
            fi
            FINAL_MSG="${FINAL_MSG}${line}\n"
        done
        # 移除最后一个多余的换行
        FINAL_MSG=$(echo -e "$FINAL_MSG" | sed -z 's/\\n$//')
        ;;
esac

# 8. 执行提交
if [ -z "$FINAL_MSG" ] || [[ "$FINAL_MSG" =~ ^[[:space:]]*$ ]]; then
    error "提交信息为空，提交中止。"
    exit 1
fi

info "正在提交更改..."
git commit -m "$FINAL_MSG"

# 9. 询问是否推送
read -p "是否推送至远程仓库 'origin/$CURRENT_BRANCH'？(y/n, 默认y): " -n 1 -r PUSH_CHOICE
echo
if [[ ! $PUSH_CHOICE =~ ^[Nn]$ ]]; then
    info "正在推送至 origin/$CURRENT_BRANCH ..."
    git push origin "$CURRENT_BRANCH"
    success "推送完成！"
else
    warning "提交已完成，但未推送。请稍后手动执行 'git push'。"
fi

success "自动化Git流程执行完毕！"

优化点解析：

1. 彩色输出 ：使用ANSI颜色代码，让终端输出信息（错误、成功、警告）一目了然，提升可读性。
2. 更健壮的检查 ：使用 git status --porcelain 来检测任何未跟踪或已修改的文件，比单纯的 git diff-index 更全面。
3. 交互式暂存 ：增加了确认环节，防止误操作暂存了不想提交的文件（如临时日志、配置文件）。
4. 增强的Prompt ：构建了更详细、指令更明确的Prompt，引导AI生成格式更规范（符合约定式提交Conventional Commits风格雏形）、信息更丰富的提交信息。同时提供了变更文件列表和diff统计，上下文更充分。
5. 灵活的编辑方式 ：提供了三种选择：(Y)直接使用AI建议、(E)在默认编辑器中编辑建议、(N)完全手动输入。特别是编辑器编辑，对于多行长信息非常友好。
6. 空信息处理 ：增加了对AI返回空信息的容错处理，避免脚本因空信息而崩溃。
7. 分支感知 ：自动获取当前分支名，并在推送时使用，避免总是推送到 master 的硬编码问题。
8. 选择性推送 ：提交后询问是否立即推送，给了用户更多的控制权。

保存这个文件。记住它的保存路径，例如 ~/Documents/scripts/git_auto_commit.sh 。

3.4 安装脚本并配置全局调用

为了让这个脚本像 git , ls 一样在任意目录都能直接运行，我们需要把它放到系统 PATH 环境变量包含的目录中，并赋予可执行权限。

对于macOS/Linux用户：

1. 在用户主目录下创建 ~/bin 目录（如果不存在）：

   mkdir -p ~/bin
   

2. 将脚本移动到这个目录：

   mv ~/Documents/scripts/git_auto_commit.sh ~/bin/git-ac
   

   技巧 ：我将脚本重命名为 git-ac (git auto-commit的缩写)，这样命令更短，输入更方便。你也可以保持原名或起其他名字。

3. 赋予脚本可执行权限：

   chmod +x ~/bin/git-ac
   

4. 将 ~/bin 添加到 PATH 。编辑你的Shell配置文件（通常是 ~/.bashrc , ~/.zshrc , 或 ~/.bash_profile ）：

   nano ~/.zshrc # 如果你用Zsh
   

   在文件末尾添加一行：

   export PATH="$HOME/bin:$PATH"
   

5. 让配置生效：

   source ~/.zshrc
   

对于Windows用户（使用Git Bash）： 步骤与上述类似，但路径和配置文件可能不同。

1. 在用户主目录创建 bin 文件夹。在Git Bash中：

   mkdir -p ~/bin
   

   ~ 在Git Bash中对应 C:\Users\<你的用户名> 。
2. 将脚本移动过去。假设脚本在 C:\Users\<你的用户名>\Desktop ：

   mv /c/Users/<你的用户名>/Desktop/git_auto_commit.sh ~/bin/git-ac
   

3. 赋予可执行权限：

   chmod +x ~/bin/git-ac
   

4. 编辑Git Bash的配置文件 ~/.bashrc ：

   nano ~/.bashrc
   

   同样在末尾添加 export PATH="$HOME/bin:$PATH" 。
5. 生效配置：

   source ~/.bashrc
   

验证安装： 打开一个新的终端窗口，输入：

git-ac --help

或者直接输入 git-ac 。如果看到脚本输出的彩色提示信息（如 [INFO] 当前目录不是一个Git仓库... ），说明安装成功。如果提示“命令未找到”，请检查 PATH 配置是否正确，并确保新终端会话已加载了更新后的配置文件。

4. 实战演示与高级用法

现在，让我们在一个真实的Git仓库中体验一下这个自动化流程的威力。

4.1 基础使用场景

假设你刚完成了一个功能的开发，修改了 src/utils/validator.js 和 tests/validator.test.js 两个文件。

1. 进入你的项目目录：

   cd ~/projects/my-awesome-app
   

2. 运行我们的自动化命令：

   git-ac
   

3. 观察输出：
   • 脚本首先会彩色高亮显示 [INFO] 当前工作分支: feature/add-user-validation 。
   • 接着列出更改的文件状态 ( git status --short )。
   • 询问“是否暂存所有更改？(y/n, 默认y):”，按回车确认。
   • 显示 [INFO] 正在请求Phi-3.5-mini分析变更并生成提交信息... ，此时Ollama模型在后台运行。
   • 几秒后，你会看到 [SUCCESS] AI生成建议成功！ ，并展示AI生成的提交信息，例如：

     === AI建议的提交信息 ===
     Add email format validation and unit tests
     
     - Implement comprehensive email format checking in `validator.js`
     - Add corresponding unit tests in `validator.test.js` to cover edge cases
     - Update validation error messages for better user feedback
     === 结束 ===
     

   • 脚本询问：“是否使用以上信息提交？(y:使用, n:手动输入, e:编辑建议):”。你可以按 y 直接使用，按 e 在编辑器中微调（比如你觉得“comprehensive”这个词用得不好），或者按 n 完全自己写。
   • 假设按 y ，脚本会执行 git commit -m “...” 。
   • 最后询问：“是否推送至远程仓库 'origin/feature/add-user-validation'？(y/n, 默认y):”。按回车确认推送。

整个过程，你只需要敲入 git-ac ，然后按几次回车，一次包含清晰描述、符合规范的提交就完成了。省去了构思摘要、回忆改了哪些文件、组织语言的精力。

4.2 结合Git Aliases实现终极快捷方式

如果你觉得 git-ac 已经很快了，那么可以把它集成到Git的别名系统里，变成 git ac ，体验更原生、更无缝。

编辑你的全局Git配置文件：

git config --global alias.ac '!git-ac'

这个命令在 ~/.gitconfig 文件中添加了一行 [alias] ac = !git-ac 。 ! 表示后面是Shell命令，而不是Git子命令。

现在，你可以在任何Git仓库中，使用更简短的命令：

git ac

它的行为与直接运行 git-ac 完全一样，但感觉更像是Git的一个内置功能，非常酷。

4.3 自定义Prompt以获得更精准的提交信息

AI生成的质量很大程度上取决于你给它的指令（Prompt）。上面的脚本已经内置了一个不错的Prompt，但你可以根据团队规范或个人喜好进行定制。

例如，你的团队严格遵循 约定式提交 (Conventional Commits) ，要求提交信息格式为 <type>(<scope>): <description> 。你可以修改脚本中的 PROMPT 变量：

PROMPT="你是一个严格遵守约定式提交规范的工程师。请根据以下代码变更，生成一条提交信息。
规范要求：
格式：<type>(<scope>): <简短描述>
其中type必须是：feat, fix, docs, style, refactor, test, chore 之一。
scope是可选的模块名。
简短描述使用祈使句，首字母不大写，结尾无句号。

在简短描述后空一行，可以写更详细的正文。

请只输出最终的提交信息。

变更文件：${CHANGED_FILES}
变更统计：${DIFF_STAT}"

这样，AI生成的提交信息就会更接近 feat(validator): add email format validation 这样的格式。

调整Prompt的技巧：

• 角色设定 ：告诉AI“你是一个...的工程师”，给它一个明确的角色，输出会更专业。
• 格式示例 ：直接给出你期望的格式样例，AI的模仿能力很强。
• 负面指令 ：明确告诉AI“不要做什么”，比如“不要输出解释性文字”、“不要使用现在完成时”。
• 上下文限定 ：只提供必要的变更信息，避免无关的代码片段，以免干扰AI判断。

你可以创建多个不同Prompt的脚本版本（如 git-ac-feat , git-ac-fix ），或者通过脚本参数来动态切换Prompt，实现更精细的控制。

5. 故障排除与经验分享

即使脚本再完善，在实际使用中也可能遇到各种问题。这里记录了我遇到的一些典型情况及其解决方法。

5.1 常见问题速查表

问题现象	可能原因	解决方案
运行 git-ac 提示“命令未找到”	1. ~/bin 目录未加入 PATH 。 2. 脚本没有可执行权限。 3. 未重新加载Shell配置。	1. 检查 echo $PATH 是否包含 ~/bin 。 2. 执行 chmod +x ~/bin/git-ac 。 3. 执行 source ~/.zshrc (或你的配置文件)。
脚本报错 ollama: command not found	Ollama未安装，或未正确添加到PATH。	1. 确认Ollama已安装 ( ollama --version )。 2. Windows用户请确保在Git Bash中安装Ollama，并重启终端。
AI生成的信息为空或乱码	1. Ollama服务未运行。 2. Phi-3.5-mini模型未正确拉取。 3. 网络问题导致模型调用失败。	1. 运行 ollama serve 启动服务（通常安装后自动运行）。 2. 运行 ollama pull phi3.5:mini 重新拉取。 3. 检查脚本中的模型名称是否正确。脚本有备用信息，可继续提交。
提交信息包含多余引号或格式错误	AI在生成时可能包含了Markdown标记或解释文本。	优化Prompt，明确要求“只输出最终的提交信息”。脚本中的Prompt已做此要求。
在Windows上脚本执行很慢	可能是Windows Defender实时扫描或NTFS文件系统开销导致。	尝试将你的项目目录和Ollama安装目录添加到Windows Defender的排除列表。
git push 失败	远程分支不存在、无权限或网络问题。	脚本已分支感知，会推送到当前分支对应的远程分支。请手动检查远程仓库状态和网络连接。

5.2 性能优化与进阶技巧

1. 使用更快的模型或量化版本 ：如果觉得Phi-3.5-mini还不够快，可以尝试更小的模型，如 phi3.5:mini 已经是量化后的版本。Ollama支持 q4_0 , q8_0 等不同精度的量化，可以在拉取时指定，例如 ollama pull phi3.5:mini-q4_0 ，以进一步减小模型体积和提升推理速度，但可能会轻微影响生成质量。

2. 缓存Ollama服务 ：确保Ollama服务在后台常驻。第一次运行 ollama run 时会加载模型到内存，稍有延迟。后续调用会快很多。可以设置Ollama在系统启动时自动运行。

3. 限制分析文件范围 ：如果你在一个大型仓库中只修改了一两个文件，但脚本默认会分析所有暂存文件。对于超大型的diff，可能会使Prompt过长，影响AI处理速度和效果。可以考虑修改脚本，只分析最近修改的N个文件，或者只分析特定后缀（如 .js , .py ）的文件。

4. 集成到IDE/编辑器 ：终极自动化是将此流程集成到你的开发环境中。例如，在VS Code中，你可以配置一个任务（Task）或使用快捷键绑定来调用这个脚本。这样，你甚至不需要切换出编辑器。

5. 团队共享与规范统一 ：将这个脚本和配置好的Prompt放到团队共享的知识库或工具脚本目录中。通过统一的Prompt，可以引导所有团队成员生成风格一致的提交信息，极大提升仓库日志的可读性和规范性。可以编写一个安装脚本，帮助新成员一键配置好这个环境。

这个由AI辅助的Git自动化流程，本质上是一个“提效小工具”。它没有改变Git的核心工作流，而是在“撰写提交信息”这个环节提供了智能辅助。经过一段时间的实践，我发现它不仅节省了时间，更重要的是，那些由AI生成的、结构清晰的提交信息，在日后回顾代码历史、进行 git blame 或者生成变更日志（CHANGELOG）时，提供了难以置信的便利。它强迫（或者说引导）你养成写规范提交信息的习惯，而这正是一个专业开发者和团队协作中不可或缺的好习惯。