GitAI - 用大模型自动生成 Git 提交信息

一个基于大语言模型的 Git 提交辅助工具，能够自动分析代码变更，生成符合规范的提交信息，并可选推送到远程仓库。

✨ 特性

• 🤖 智能生成：基于大语言模型，自动生成高质量的 Git 提交信息
• 🌍 多平台支持：支持 OpenAI、Claude、Gemini、Ollama、DeepSeek、通义千问等 15+ 主流平台
• 📝 规范提交：支持 Conventional Commits 规范，自动生成格式化的提交信息
• 🌐 多语言：支持中文、英文、日文等多种语言的提交信息
• ⚙️ 灵活配置：支持配置文件、环境变量、命令行参数三种配置方式
• 🔒 安全可靠：支持本地部署的 Ollama，代码不会上传到第三方服务
• 🚀 自动推送：可选自动推送到远程仓库，提高工作效率
• 💾 智能记忆：自动记住上次使用的命令参数，下次直接运行 gitai 即可复用

📦 安装

方式一：从源码安装（开发模式）

# 克隆项目
git clone <repository-url>
cd gitai

# 安装依赖（开发模式）
pip install -e .

# 或者直接运行模块
python -m gitai

方式二：从 PyPI 安装（发布后）

pip install gitai-agent

依赖要求

• Python 3.9 或更高版本
• Git（用于版本控制操作）

🚀 快速开始

1. 查看支持的平台

gitai --list-providers

2. 使用 Ollama 本地模型（推荐，无需 API Key）

# 确保已安装并启动 Ollama
# ollama pull qwen2.5-coder:7b
# ollama serve

# 使用本地模型生成提交信息
gitai -p ollama -m qwen2.5-coder:7b -y

3. 使用 OpenAI

# 设置 API Key
export OPENAI_API_KEY=sk-xxxx

# 生成并提交
gitai -p openai -m gpt-4o-mini -y

4. 使用 DeepSeek

# 设置 API Key
export DEEPSEEK_API_KEY=sk-xxxx

# 生成中文提交信息并推送
gitai -p deepseek -l zh -y --push

📖 使用指南

核心工作流

整个 Agent 的执行流程如下：

1. 检测变更：默认自动执行 git add -A，将工作区和暂存区的改动都纳入分析范围。如果只想提交已暂存内容，可以使用 --only-staged 参数。

2. 生成提交信息：将变更的统计信息、diff 内容、最近历史提交一起发送给大模型，支持 Conventional Commits 和简单摘要两种风格，还能指定语言（如中文）。

3. 人工确认或直接提交：默认会展示生成的提交信息并询问确认：

   • y - 确认提交
   • e - 编辑提交信息
   • r - 重新生成
   • n - 取消操作

   使用 -y 参数可跳过交互确认。

4. 提交并推送：确认后执行 git commit，添加 --push 参数会自动推送到远程仓库。如果当前分支没有上游，会自动设置 -u origin <branch>。

常见使用场景

场景	命令	说明
分析并提交	gitai	分析全部改动并提交（首次交互确认，后续复用上次参数）
强制交互确认	gitai -i	覆盖上次保存的参数，强制进入交互模式
跳过确认直接提交	gitai -y	自动生成并提交
提交并推送	gitai -y --push	提交后推送到 origin
指定平台和模型	gitai -p openai -m gpt-4o -y	使用 OpenAI GPT-4o
使用 Ollama 本地模型	gitai -p ollama -m qwen2.5-coder:7b -l zh -y	本地部署，无需 API Key
只提交已暂存内容	gitai --only-staged	不自动执行 git add
只生成不提交	gitai --dry-run	查看生成的提交信息
查看支持的平台	gitai --list-providers	列出所有支持的平台
生成中文提交信息	gitai -l zh	使用中文生成提交信息
额外排除文件	gitai --exclude "*.csv" --exclude "data/*"	排除特定文件
使用自定义端点	gitai -p custom --api-base http://host/v1 -m my-model	接入任意 OpenAI 兼容服务

💾 智能记忆功能

GitAI 会自动记住你上次使用的命令参数，下次直接运行 gitai 即可复用，无需重复输入。

工作原理：

1. 当你使用特定参数运行 gitai 时（如 gitai -p zhipu -y --push），这些参数会被自动保存
2. 下次直接运行 gitai（不带任何参数）时，工具会自动加载并使用上次保存的参数
3. 参数状态文件保存在 ~/.config/gitai/last_args.json（Windows: C:\Users\<用户名>\.config\gitai\last_args.json）

使用示例：

# 第一次：使用特定参数运行
gitai -p zhipu -y --push

# 之后：直接运行 gitai，自动复用 -p zhipu -y --push 参数
gitai

# 如果想使用不同的参数，直接指定即可（会覆盖上次保存的参数）
gitai -p ollama -m qwen2.5-coder:7b -y

# 再次直接运行，会使用最新的参数
gitai

注意事项：

• 只有当你显式提供参数时，才会保存参数状态
• 运行 gitai --help、gitai --list-providers 等查询命令不会保存参数
• 如果想恢复默认行为，可以删除状态文件：rm ~/.config/gitai/last_args.json
• 如果上次保存了 -y 参数，但这次想进入交互模式，可以使用 -i 或 --interactive 强制进入交互模式：

  # 上次保存的是 -y --push，这次强制进入交互模式
  gitai -i --push
  

⚙️ 配置方式

GitAI 支持三种配置方式，优先级从高到低：

1. 命令行参数（如 --model、--api-base）
2. 环境变量（GITAI_* 前缀）
3. 配置文件（.gitai.toml 或 ~/.config/gitai/config.toml）
4. 内置默认值

配置文件

在项目根目录创建 .gitai.toml 文件：

[gitai]
# 大模型平台配置
provider = "ollama"
model = "qwen2.5-coder:7b"
api_base = "http://localhost:11434"

# 生成参数
language = "zh"
style = "conventional"
temperature = 0.2
max_diff_chars = 40000
max_file_chars = 12000

# Git 行为
auto_stage = true
auto_push = false
push_remote = "origin"

# 额外的项目约定
extra_instructions = """
- 这是一个 Python 项目，遵循 PEP 8
- scope 优先使用模块名：cli / config / llm / git
"""

# 排除的文件模式
exclude_patterns = [
    "*.lock",
    "package-lock.json",
    "*.min.js",
    "dist/*",
    "node_modules/*",
]

环境变量

复制 .env.example 为 .env 并设置相应的 API Key：

# 设置 OpenAI API Key
export OPENAI_API_KEY=sk-xxxx

# 或者使用 DeepSeek
export DEEPSEEK_API_KEY=sk-xxxx

# 配置 GitAI
export GITAI_PROVIDER=ollama
export GITAI_MODEL=qwen2.5-coder:7b
export GITAI_LANGUAGE=zh
export GITAI_AUTO_PUSH=false

查看生效的配置

gitai --print-config

🎯 提交信息风格

Conventional Commits（默认）

严格遵循 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

• type: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
• scope: 可选，模块名称（如 api, cli, deps）
• subject: 祈使句，小写开头，不超过 72 字符
• body: 详细描述改动（可选）
• footer: 破坏性变更说明（可选）

Simple 模式

简单摘要风格，适合小型项目或个人项目：

<summary>

<body>

• summary: 简洁的摘要，不超过 72 字符
• body: 改动细节与原因（可选）

🔧 高级用法

自定义 OpenAI 兼容端点

任何提供 OpenAI 兼容 API 的服务都可以接入：

gitai -p custom --api-base http://your-host:8000/v1 -m your-model -y

编辑器集成

提交信息确认时可以选择编辑：

• 按 e 进入编辑模式
• 使用 $EDITOR 环境变量指定的编辑器
• 支持设置 GITAI_EDITOR 或 GIT_EDITOR 覆盖默认编辑器

跳过 Git Hooks

gitai -y --no-verify

查看帮助

gitai --help

🏗️ 项目结构

gitai/
├── gitai/
│   ├── __init__.py      # 包初始化
│   ├── __main__.py      # 模块入口
│   ├── agent.py         # Agent 主流程
│   ├── cli.py           # 命令行接口
│   ├── config.py        # 配置管理
│   ├── context.py       # 上下文构建
│   ├── git_utils.py     # Git 工具函数
│   └── llm.py           # 大模型调用层
├── tests/               # 测试文件
├── pyproject.toml       # 项目配置
├── .gitai.toml          # 示例配置文件
├── .env.example         # 环境变量示例
└── README.md            # 项目文档

🧪 开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest

代码格式化

ruff format .
ruff check .

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🙏 致谢

• litellm - 统一的大模型调用层
• Ollama - 本地大模型部署工具
• 所有贡献者和使用者

📞 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者。