项目提交指南

请确保每次提交都包含以下信息：

1. 类型: 使用符合 Conventional Commits 格式的前缀，例如 feat:、fix:、docs: 等。
2. 描述: 简洁明了地说明本次提交的目的和内容。
3. 关联问题: 如果提交与特定问题相关，请在提交信息中提及问题编号或链接。

示例：

feat: 添加用户注册功能
fix: 修复登录页面的样式问题
docs: 更新 README 文件中的使用说明

请注意：所有提交必须遵循上述格式，以保持代码库的一致性和可维护性。

需求

• 使用带有以下作用域的规范提交：auth、api、ui、db
• 如果有工单号，请一并注明（例如：JIRA-123）
• 安全相关变更必须明确标注
• 破坏性变更需要在消息中包含 BREAKING CHANGE

项目背景

这是一个处理敏感数据的金融服务API。 请在提交信息中强调安全性、合规性和性能。

请参阅本仓库中的 [`COMMIT_MESSAGE.md.example`](COMMIT_MESSAGE.md.example)，以获取完整示例。

使用方法

命令示例

# 使用完整命令名
npx git-rewrite-commits [options]

# 或使用简短别名 (grec)
npx grec [options]

常见用法：

# 重写整个 Git 历史
npx git-rewrite-commits

# 预览更改而不应用（试运行）
npx git-rewrite-commits --dry-run

# 为暂存的更改生成提交信息
npx git-rewrite-commits --staged

# 仅处理最近 10 条提交
npx git-rewrite-commits --max-commits 10

# 使用自定义 AI 模型
npx git-rewrite-commits --model gpt-4

# 使用 Ollama 的本地 AI
npx git-rewrite-commits --provider ollama

# 安装或更新 Git 钩子
npx git-rewrite-commits --install-hooks

实际案例

自动化提交信息生成

两个智能钩子：

1. pre-commit：预览 AI 生成的信息，并可选择替换不良提交信息
2. prepare-commit-msg：自动生成功能或使用已批准的信息

# 安装钩子（任选其一）
npx git-rewrite-commits --install-hooks
# 或
npx grec --install-hooks

# 启用它们（出于安全考虑需手动开启）
git config hooks.preCommitPreview true    # 提交前预览
git config hooks.prepareCommitMsg true    # 编辑器中自动生成

# 配置提供商
git config hooks.commitProvider ollama  # 或使用 OpenAI 并设置 OPENAI_API_KEY
git config hooks.providerModel llama3.2  # 可选：指定模型

现在当你执行 git commit 时：

• 使用 pre-commit 钩子：你会先看到 AI 生成的信息预览
• 使用 prepare-commit-msg 钩子：AI 生成的信息会出现在编辑器中

手动重写现有提交

# 在推送前清理最近 5 条提交
echo "🔧 正在优化提交信息以便推送..."
npx git-rewrite-commits --max-commits 5 --dry-run

echo "是否应用更改？(y/n)"
read answer
if [ "$answer" = "y" ]; then

快速修复的别名

添加到你的 ~/.gitconfig 或 ~/.zshrc/~/.bashrc 文件中：

# Git 别名
git config --global alias.fix-commits '!npx git-rewrite-commits --max-commits'

# 使用方法：git fix-commits 3

# Shell 别名
alias fix-last-commit='npx git-rewrite-commits --max-commits 1 --skip-backup'
alias fix-branch='npx git-rewrite-commits --max-commits 20'

# 使用方法：fix-last-commit

团队工作流程：特性分支清理

在创建拉取请求之前：

# 1. 检查需要修复的内容
npx git-rewrite-commits --dry-run --max-commits 10

# 2. 应用改进
npx git-rewrite-commits --max-commits 10

# 3. 强制推送到你的特性分支
git push --force-with-lease origin feature-branch

CI/CD 集成

将以下内容添加到你的 CI 流水线（例如 GitHub Actions）中，用于验证拉取请求：

- name: 检查提交质量
  run: |
    npx git-rewrite-commits --dry-run --max-commits ${{ github.event.pull_request.commits }}
    # 这将显示哪些提交可以被改进

准备开源

在将私有仓库公开之前：

# 使用自定义模板修复所有提交
npx git-rewrite-commits \
  --template "feat(scope): message" \
  --language en \
  --no-skip-well-formed

# 检查更改
git log --oneline -20

# 如果满意，强制推送
git push --force-with-lease origin main

工作原理

1. 分析：读取你暂存的更改或提交历史
2. 生成：利用 AI 创建有意义的规范提交信息
3. 应用：用更好的信息更新你的提交

智能信息替换

当你使用 git commit -m "bad message" 时，pre-commit 钩子可以：

• 推荐更好的 AI 生成信息
• 在你批准后替换掉原来的差劲信息
• 在提交编辑器中显示被替换的内容

历史重写流程

1. 创建备份：保存当前分支状态
2. 重写历史：使用 git filter-branch 应用新信息
3. 提供恢复功能：保留备份分支，以备不时之需

贡献

欢迎贡献！请随时提交 Pull Request。对于重大更改，请先打开一个议题讨论你想要修改的内容。

1. 分支仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改（使用规范提交！）
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

许可证

本项目采用 MIT 许可证——详情请参阅 LICENSE 文件。

错误报告

如果你发现任何错误，请在此处提交问题：https://github.com/f/git-rewrite-commits/issues

联系方式

如有疑问或需要支持，请在 GitHub 仓库中提交问题。

---

请记住：在重写历史之前务必备份你的仓库！ 🔒

git-rewrite-commits 快速上手指南

git-rewrite-commits 是一款基于 AI 的 Git 提交信息重写工具，能够自动将混乱的提交历史优化为符合规范（Conventional Commits）的格式。非常适合在开源项目发布前或提升仓库可维护性时使用。

⚠️ 重要警告：此工具会重写 Git 历史（修改 Commit Hash）。

• ✅ 适用场景：个人项目公开前、特性分支合并前、本地提交整理。
• ❌ 禁止场景：多人协作的主分支、他人已拉取的共享分支。重写历史需要强制推送（force push），可能导致团队工作流中断。

环境准备

• 操作系统：Windows, macOS, Linux
• 前置依赖：
  • Node.js (推荐 v16+) 和 npm
  • Git
• AI 提供商（二选一）：
  1. OpenAI（云端）：需准备 OPENAI_API_KEY。
  2. Ollama（本地，推荐用于敏感代码）：需安装 Ollama 并下载模型（如 llama3.2 或 gemma3）。

安装步骤

无需全局安装，推荐使用 npx 直接运行（按需加载）：

# 方式一：使用完整命令
npx git-rewrite-commits

# 方式二：使用简短别名 (grec)
npx grec

若需全局安装以便随时调用：

npm install -g git-rewrite-commits
# 或安装简短别名
npm install -g grec

基本使用

场景一：快速生成单次提交信息

设置好环境变量后，可直接用于生成当前暂存区的提交信息：

# 1. 设置 OpenAI Key (Unix/macOS)
export OPENAI_API_KEY="your-api-key"

# 2. 执行提交（自动分析暂存区文件并生成规范消息）
git add -A
git commit -m "$(npx -y grec --quiet --staged --skip-remote-consent)"

注：若使用本地 Ollama，请确保 ollama serve 已运行，并添加 --provider ollama 参数。

场景二：重写最近的提交历史

清理最近 N 条提交记录，使其符合规范：

# 预览变更（不实际执行，安全检查）
npx grec --dry-run --max-commits 5

# 确认无误后，执行重写（会自动创建备份分支）
npx grec --max-commits 5

# 如果满意结果，推送到远程（注意：需要强制推送）
git push --force-with-lease origin <branch-name>

场景三：配置本地 AI (保护隐私)

对于包含敏感代码的项目，建议使用本地模型：

# 1. 拉取并运行本地模型
ollama pull llama3.2
ollama serve

# 2. 配置工具使用 Ollama
git config hooks.commitProvider ollama
git config hooks.providerModel llama3.2

# 3. 执行重写
npx grec --max-commits 10

进阶：自定义项目规范

在项目根目录创建 COMMIT_MESSAGE.md 文件，AI 将遵循其中的约定（如 Scope 范围、JIRA 票号格式等）：

# Project Commit Guidelines

## Requirements
- Scopes: auth, api, ui, db
- Include ticket numbers (e.g., JIRA-123)
- Language: Chinese

工具会自动读取该文件以生成更符合团队风格的提交信息。