返回文章

git-muse：让 commit message 少一点敷衍，多一点准确

git-muse 是一个 Git 辅助工具，根据已暂存（staged）的改动自动生成 Conventional Commit 格式的提交信息，用户确认后使用原生 git commit 提交。

写代码时，很多人最不想花时间的环节，是写 commit message。

不是不会写，而是麻烦。改了三五个文件，修了一个边界问题，顺手补了测试，再调整一点文档。真正提交时，脑子里只剩下两个字：差不多。于是仓库里慢慢出现这些记录：

fix
update
wip

改一下

调整代码

短期看没问题，代码能提交就行。可等到回头排查问题、看版本变更、整理发布记录时，这些 commit message 基本没有价值。你不知道当时改了什么，也不知道为什么改，更不知道影响范围在哪里。

git-muse 解决的就是这个小但高频的问题：根据已暂存的改动，生成一条可用、可编辑、格式稳定的 commit message。

它不是替代 Git，也不是让 AI 接管提交。它更像一个 Git 辅助工具：帮你看一眼 staged diff，给出一条靠谱的提交说明，最后仍然由你确认，再交给原生 git commit 完成提交。

1. 解决什么问题

写 commit message 太随意

很多项目的提交记录不是坏在代码，而是坏在信息密度太低。

一条好的 commit message 至少应该回答几个问题：

这次改了什么？

影响哪个模块？

是新功能、修复、重构，还是文档变更？

以后回看时能不能快速理解？

但日常开发节奏很快，尤其是小改动、多文件改动、临时修 bug 时，很容易随手写一句 fix。这种提交当时省了十秒，后面排查问题可能多花十分钟。

git-muse 会读取 git diff --cached，也就是已经 git add 的内容，根据真实改动生成 Conventional Commit 风格的候选消息，例如：

fix(auth): handle expired refresh token

或者中文输出：

fix(auth): 修复刷新令牌过期处理

这样提交记录不会只剩“改了点东西”。

AI 工具容易越界

直接把整个仓库丢给 AI，让它帮你总结提交，看起来方便，但问题不少：

它可能读到不该读的文件。

它可能把未暂存的改动也算进去。

它可能生成看起来像样但不符合项目规则的 message。

它可能直接替你提交，风险太高。

git-muse 的边界更窄，也更清楚。

默认只读取 staged changes，也就是你明确准备提交的内容。未 git add 的改动不会被拿来生成 commit message。提交前会让你确认、编辑、重新生成或取消，不会悄悄替你做决定。

提交流程不该破坏 Git 原有行为

很多工具为了方便，会绕过 Git 原本的提交流程。这样可能影响 hooks、签名、编辑器、credential helper 等本地配置。

git-muse 不重造 Git。真正提交时，它使用：

git commit -F <message-file>

这意味着原来的 Git hooks、签名、编辑器行为都还在。它只是帮你准备 message，不抢 Git 的工作。

团队需要稳定格式

团队协作中，commit message 不只是给人看的，也常被用来生成 changelog、判断版本类型、做发布说明。

git-muse 默认生成 Conventional Commits 格式：

<type>[optional scope]: <subject>

比如：

feat(cli): add inspect command

fix(diff): filter env files from context

docs(readme): update provider setup guide

格式稳定之后，提交历史更容易读，自动化工具也更容易处理。

2. 特点和功能

只分析已暂存改动

git-muse 默认读取：

git diff --cached

这点很关键。

你工作区里可能有很多临时改动，但只有 git add 过的内容才代表“这次准备提交”。git-muse 只看这部分，生成结果更贴近当前提交，也避免把未完成代码混进 message。

典型流程是：

git add <files>

git muse inspect

git muse

生成 Conventional Commit

工具会根据改动内容生成提交消息候选，默认使用 Conventional Commits 风格。

支持常见类型：

feat
fix
docs
style
refactor
perf
test
build
ci
chore
revert

这样生成出来的 message 不只是“像一句话”，而是有结构、能归类、方便团队长期维护。

支持确认、编辑、重新生成、取消

git-muse 不会把模型输出直接当最终结果。

默认交互类似这样：

Suggested commit message:
feat(auth): add refresh token rotation
[c] commit [e] edit [r] regenerate [v] view diff [q] quit
>

你可以直接提交，也可以编辑、重新生成、查看 diff，或者退出。

这比“AI 直接替你提交”安全得多。模型只给建议，最终决定仍然在人手里。

使用原生 Git 提交

提交动作交给系统 Git 完成，而不是工具自己模拟 Git 行为。

实际使用：

git commit -F <message-file>

这样可以保留项目已有的：

pre-commit hook

commit-msg hook

GPG / SSH 签名

Git editor

credential helper

工具只做辅助，不破坏本地开发习惯。

支持 Ollama 和 OpenAI-compatible API

git-muse 支持本地模型和在线模型两种路线。

本地模型可以用 Ollama，例如：

git config --global muse.provider ollama
git config --global muse.baseUrl http://localhost:11434
git config --global muse.model qwen2.5-coder

OpenAI-compatible API 也可以配置：

git config --global muse.provider compatible
git config --global muse.baseUrl https://api.openai.com/v1
git config --global muse.model gpt-4.1-mini

API key 只从环境变量读取，不写进项目配置：

OPENAI_API_KEY

OPENROUTER_API_KEY

ANTHROPIC_API_KEY

GEMINI_API_KEY

这个设计比较克制，避免把密钥写进 Git config、仓库文件或日志。

提供 inspect，看清楚发给模型的内容

如果你担心“到底哪些内容会发给模型”，可以先运行：

git muse inspect

它会展示将要发送给 LLM 的上下文摘要，包括文件数量、纳入内容、排除原因等。

例如：

Provider: ollama
Model: qwen2.5-coder
Files changed: 5
Included bytes: 8420
Excluded:
.env.local secret pattern
dist/app.js generated file
pnpm-lock.yaml large lockfile

这让工具的行为更透明。尤其在公司项目或私有仓库里，提交辅助工具必须能说清楚自己读了什么、发了什么、排除了什么。

提供 doctor，快速排查环境问题

如果配置不对、模型连不上、没有 staged changes，可以用：

git muse doctor

它会检查 Git 仓库状态、暂存区、provider、model、API key、网络等信息。

目标不是输出一大堆调试日志，而是告诉你下一步该做什么。

支持代理配置

访问在线模型时，可能需要代理。git-muse 支持命令行、环境变量和配置文件多种方式。

命令行：

git muse --proxy http://127.0.0.1:7890

环境变量：

GIT_MUSE_PROXY

配置文件：

{
  "llm": {
    "proxy": "http://127.0.0.1:7890"
  }
}

代理优先级清楚：

--proxy > GIT_MUSE_PROXY > ~/.git-muse.json > muse.proxy

可配置输出语言

如果团队使用中文提交说明，可以在配置里设置：

{
  "output": {
    "language": "zh"
  }
}

默认支持：

en

zh

英文项目用英文，中文团队用中文，不强行绑定一种风格。

过滤敏感文件和大文件

git-muse 默认会避开 secrets、证书、.env*、生成文件和过大的 diff。

也可以通过配置补充忽略规则：

{
  "diff": {
    "maxBytes": 100000,
    "ignore": ["*.lock", "coverage/*"],
    "allow": [".env.example"]
  }
}

这类功能不显眼，但很重要。commit message 工具不该为了省事，把敏感内容塞进模型上下文。

暂无评论