Skip to content

Commit e237b99

Browse files
jinzhongjiajinzhongjia
committed
docs: update documentation for v17.5.0 compatibility and improve Chinese localization
- Add important note about variable and tool syntax change in v17.5.0 - Add complete Chinese translation of README - Update Makefile to save documentation to root directory - Refresh documentation with latest upstream changes - Remove outdated documentation file
1 parent cdaf830 commit e237b99

File tree

6 files changed

+810
-5736
lines changed

6 files changed

+810
-5736
lines changed

‎Makefile

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
OS := $(shell uname -s 2>/dev/null || echo Windows_NT)
44

55
# Default output path for the downloaded doc
6-
DOC_OUT := doc/codecompanion.txt
6+
DOC_OUT := codecompanion.txt
77

88
# Windows (PowerShell 7) target
99
ifeq ($(OS),Windows_NT)
@@ -20,7 +20,6 @@ WGET := $(shell command -v wget 2>/dev/null)
2020
URL := https://github.com/olimorris/codecompanion.nvim/raw/refs/heads/main/doc/codecompanion.txt
2121

2222
doc:
23-
@mkdir -p doc
2423
ifeq ($(CURL),)
2524
ifeq ($(WGET),)
2625
@echo "Error: need curl or wget to download on non-Windows" && exit 1

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
A Neovim plugin extension for CodeCompanion that generates AI-powered Git commit messages following the Conventional Commits specification, with comprehensive Git workflow integration.
44

5+
> [!IMPORTANT]
6+
> As of CodeCompanion v17.5.0, variables and tools must be wrapped in curly braces, such as `@{git_read}` or `#{buffer}`
7+
58
## ✨ Features
69

710
- 🤖 **AI Commit Generation** - Generate Conventional Commits compliant messages using CodeCompanion's LLM adapters

‎README_zh.md

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
# CodeCompanion GitCommit 扩展
2+
3+
一个为 CodeCompanion 开发的 Neovim 插件扩展，用于生成遵循约定式提交规范的 AI 驱动 Git 提交信息，并提供全面的 Git 工作流集成。
4+
5+
> [!IMPORTANT]
6+
> 从 CodeCompanion v17.5.0 开始，变量和工具必须用花括号包裹，例如 `@{git_read}` 或 `#{buffer}`
7+
8+
## ✨ 功能特性
9+
10+
- 🤖 **AI 提交信息生成** - 使用 CodeCompanion 的 LLM 适配器生成符合约定式提交规范的提交信息
11+
- 🛠️ **Git 工具集成** - 在聊天中通过 `@{git_read}`（16 个读取操作）和 `@{git_edit}`（17 个写入操作）工具执行 Git 操作
12+
- 🤖 **Git 助手** - 通过 `@{git_bot}` 提供智能 Git 工作流辅助，结合读写操作
13+
- 🌍 **多语言支持** - 支持生成多种语言的提交信息
14+
- 📝 **智能缓冲区集成** - 在 gitcommit 缓冲区中自动生成提交信息，支持可配置的快捷键
15+
- 📋 **文件过滤** - 支持使用 glob 模式从差异分析中排除文件
16+
- 📚 **提交历史上下文** - 使用最近的提交历史来保持一致的风格和模式
17+
- 🔌 **编程 API** - 为外部集成和自定义工作流提供完整的 API
18+
- ⚡ **异步操作** - 非阻塞的 Git 操作，具有适当的错误处理
19+
20+
## 📦 安装
21+
22+
将此扩展添加到你的 CodeCompanion 配置中：
23+
24+
```lua
25+
require("codecompanion").setup({
26+
extensions = {
27+
gitcommit = {
28+
callback = "codecompanion._extensions.gitcommit",
29+
opts = {
30+
-- 基本配置
31+
adapter = "openai", -- LLM 适配器
32+
model = "gpt-4", -- 模型名称
33+
languages = { "English", "Chinese", "Japanese", "French" }, -- 支持的语言
34+
35+
-- 文件过滤（可选）
36+
exclude_files = {
37+
"*.pb.go", "*.min.js", "*.min.css", "package-lock.json",
38+
"yarn.lock", "*.log", "dist/*", "build/*", ".next/*",
39+
"node_modules/*", "vendor/*"
40+
},
41+
42+
-- 缓冲区集成
43+
buffer = {
44+
enabled = true, -- 启用 gitcommit 缓冲区快捷键
45+
keymap = "<leader>gc", -- 生成提交信息的快捷键
46+
auto_generate = true, -- 进入缓冲区时自动生成
47+
auto_generate_delay = 200, -- 自动生成延迟（毫秒）
48+
skip_auto_generate_on_amend = true, -- 在 git commit --amend 时跳过自动生成
49+
},
50+
51+
-- 功能开关
52+
add_slash_command = true, -- 添加 /gitcommit 斜杠命令
53+
add_git_tool = true, -- 添加 @{git_read} 和 @{git_edit} 工具
54+
enable_git_read = true, -- 启用只读 Git 操作
55+
enable_git_edit = true, -- 启用写入 Git 操作
56+
enable_git_bot = true, -- 启用 @{git_bot} 工具组（需要同时启用读写）
57+
add_git_commands = true, -- 添加 :CodeCompanionGitCommit 命令
58+
git_tool_auto_submit_errors = false, -- 自动提交错误给 LLM
59+
git_tool_auto_submit_success = true, -- 自动提交成功信息给 LLM
60+
gitcommit_select_count = 100, -- /gitcommit 中显示的提交数量
61+
62+
-- 提交历史上下文（可选）
63+
use_commit_history = true, -- 启用提交历史上下文
64+
commit_history_count = 10, -- 用于上下文的最近提交数量
65+
}
66+
}
67+
}
68+
})
69+
```
70+
71+
## 🚀 使用方法
72+
73+
### 命令
74+
75+
| 命令 | 描述 |
76+
|---------|-------------|
77+
| `:CodeCompanionGitCommit` | 生成 Git 提交信息 |
78+
| `:CCGitCommit` | 生成 Git 提交信息（简短别名） |
79+
80+
### Git 工具操作
81+
82+
在 CodeCompanion 聊天中使用 Git 工具：
83+
84+
#### 📖 只读操作（`@{git_read}`）
85+
86+
```
87+
@{git_read} status # 显示仓库状态
88+
@{git_read} log --count 5 # 显示最近 5 个提交
89+
@{git_read} diff --staged # 显示暂存的更改
90+
@{git_read} branch # 列出所有分支
91+
@{git_read} contributors --count 10 # 显示前 10 个贡献者
92+
@{git_read} tags # 列出所有标签
93+
@{git_read} generate_release_notes # 生成最新标签之间的发布说明
94+
@{git_read} generate_release_notes --from_tag "v1.0.0" --to_tag "v1.1.0" # 生成特定标签之间的发布说明
95+
@{git_read} gitignore_get # 获取 .gitignore 内容
96+
@{git_read} gitignore_check --gitignore_file "file.txt" # 检查文件是否被忽略
97+
@{git_read} show --commit_hash "abc123" # 显示提交详情
98+
@{git_read} blame --file_path "src/main.lua" # 显示文件追溯信息
99+
@{git_read} search_commits --pattern "fix:" # 搜索包含 "fix:" 的提交
100+
@{git_read} stash_list # 列出所有暂存
101+
@{git_read} diff_commits --commit1 "abc123" --commit2 "def456" # 比较两个提交
102+
@{git_read} remotes # 显示远程仓库
103+
@{git_read} help # 显示帮助信息
104+
```
105+
106+
#### ✏️ 写入操作（`@{git_edit}`）
107+
108+
```
109+
@{git_edit} stage --files ["src/main.lua", "README.md"]
110+
@{git_edit} unstage --files ["src/main.lua"]
111+
@{git_edit} commit --commit_message "feat(api): 添加新功能"
112+
@{git_edit} commit # 自动生成 AI 提交信息
113+
@{git_edit} create_branch --branch_name "feature/new-ui" --checkout true
114+
@{git_edit} checkout --target "main"
115+
@{git_edit} stash --message "进行中的工作" --include_untracked true
116+
@{git_edit} apply_stash --stash_ref "stash@{0}"
117+
@{git_edit} reset --commit_hash "abc123" --mode "soft"
118+
@{git_edit} gitignore_add --gitignore_rules ["*.log", "temp/*"]
119+
@{git_edit} gitignore_remove --gitignore_rule "*.tmp"
120+
@{git_edit} push --remote "origin" --branch "main" --set_upstream true
121+
@{git_edit} cherry_pick --cherry_pick_commit_hash "abc123"
122+
@{git_edit} revert --revert_commit_hash "abc123"
123+
@{git_edit} create_tag --tag_name "v1.0.0" --tag_message "发布 v1.0.0"
124+
@{git_edit} delete_tag --tag_name "v0.9.0"
125+
@{git_edit} merge --branch "feature/new-ui"
126+
```
127+
128+
#### 🤖 Git 助手（`@{git_bot}`）
129+
130+
使用综合性的 Git 助手，结合读写操作：
131+
132+
```
133+
@{git_bot} 请帮我创建新分支并推送当前更改
134+
@{git_bot} 分析最近的提交历史并总结主要变化
135+
@{git_bot} 帮我整理当前工作区状态
136+
```
137+
138+
### 基本用法
139+
140+
**1. 生成提交信息：**
141+
```
142+
:CodeCompanionGitCommit
143+
```
144+
145+
**2. GitCommit 缓冲区集成：**
146+
- 运行 `git commit` 打开提交缓冲区
147+
- 按 `<leader>gc` 生成提交信息（如果启用了自动生成则会自动生成）
148+
- 编辑并保存以完成提交
149+
150+
**3. 基于聊天的 Git 工作流：**
151+
```
152+
@{git_read} status # 检查仓库状态
153+
@{git_edit} stage --files ["file1.txt", "file2.txt"] # 暂存文件
154+
/gitcommit # 选择提交并插入其内容作为参考
155+
@{git_edit} commit --commit_message "feat(api): 添加新功能" # 提交
156+
@{git_edit} push --remote "origin" --branch "main" # 推送更改
157+
@{git_read} generate_release_notes # 生成最新标签之间的发布说明
158+
```
159+
160+
**4. 生成发布说明：**
161+
```
162+
@{git_read} generate_release_notes # 自动检测最新和前一个标签
163+
@{git_read} generate_release_notes --from_tag "v1.0.0" --to_tag "v1.1.0" # 指定标签
164+
@{git_read} generate_release_notes --release_format "json" # JSON 格式输出
165+
```
166+
167+
## ⚙️ 配置选项
168+
169+
<details>
170+
<summary>完整配置选项</summary>
171+
172+
```lua
173+
opts = {
174+
adapter = "openai", -- LLM 适配器
175+
model = "gpt-4", -- 模型名称
176+
languages = { "English", "Chinese", "Japanese", "French" }, -- 支持的语言列表
177+
exclude_files = { -- 排除的文件模式
178+
"*.pb.go", "*.min.js", "*.min.css",
179+
"package-lock.json", "yarn.lock", "*.log",
180+
"dist/*", "build/*", ".next/*",
181+
"node_modules/*", "vendor/*"
182+
},
183+
add_slash_command = true, -- 添加 /gitcommit 命令
184+
add_git_tool = true, -- 添加 Git 工具
185+
enable_git_read = true, -- 启用只读 Git 操作
186+
enable_git_edit = true, -- 启用写入 Git 操作
187+
enable_git_bot = true, -- 启用 @{git_bot} 工具组（需要同时启用读写）
188+
add_git_commands = true, -- 添加 Git 命令
189+
gitcommit_select_count = 100, -- /gitcommit 中显示的提交数
190+
git_tool_auto_submit_errors = false, -- 自动提交错误给 LLM
191+
git_tool_auto_submit_success = true, -- 自动提交成功信息给 LLM
192+
use_commit_history = true, -- 启用提交历史上下文
193+
commit_history_count = 10, -- 用于上下文的最近提交数量
194+
buffer = {
195+
enabled = true, -- 启用缓冲区集成
196+
keymap = "<leader>gc", -- 快捷键
197+
auto_generate = true, -- 自动生成
198+
auto_generate_delay = 200, -- 生成延迟（毫秒）
199+
skip_auto_generate_on_amend = true, -- 修订时跳过自动生成
200+
}
201+
}
202+
```
203+
204+
</details>
205+
206+
## 🔌 编程 API
207+
208+
该扩展为外部集成提供了全面的 API：
209+
210+
```lua
211+
local gitcommit = require("codecompanion._extensions.gitcommit")
212+
213+
-- 以编程方式生成提交信息
214+
gitcommit.exports.generate("Chinese", function(result, error)
215+
if result then
216+
print("生成的提交信息：", result)
217+
else
218+
print("错误：", error)
219+
end
220+
end)
221+
222+
-- 检查是否在 git 仓库中
223+
if gitcommit.exports.is_git_repo() then
224+
print("在 git 仓库中")
225+
end
226+
227+
-- 获取 git 状态
228+
local status = gitcommit.exports.git_tool.status()
229+
print("Git 状态：", status)
230+
231+
-- 暂存文件
232+
gitcommit.exports.git_tool.stage({"file1.txt", "file2.txt"})
233+
234+
-- 创建并切换分支
235+
gitcommit.exports.git_tool.create_branch("feature/new-feature", true)
236+
237+
-- 生成特定标签之间的发布说明（包含所有参数）
238+
local success, notes, user_msg, llm_msg = gitcommit.exports.git_tool.generate_release_notes("v1.0.0", "v1.1.0", "markdown")
239+
if success then
240+
print("发布说明：", notes)
241+
end
242+
243+
-- 生成发布说明（自动检测最新的两个标签）
244+
local success, notes = gitcommit.exports.git_tool.generate_release_notes()
245+
```
246+
247+
## 📚 文档
248+
249+
详细文档请查看：`:help codecompanion-gitcommit`
250+
251+
## 🔒 安全特性
252+
253+
- **只读操作**（`@{git_read}`）无需确认
254+
- **修改操作**（`@{git_edit}`）需要用户确认
255+
- **仓库验证**确保操作在有效的 Git 仓库中进行
256+
- **全面的错误处理**提供有用的错误信息
257+
258+
## 📄 许可证
259+
260+
MIT 许可证

0 commit comments

Comments
 (0)