Gitool 文件提交

Gitool 是一个面向桌面版 VS Code 的独立 Git 提交工作台。它把提交信息、当前变更和提交历史拆成三个可折叠、可拖动调整的区域，在保留 VS Code 原生 Git 行为的同时支持按文件选择提交。

功能

• 在独立的 Gitool 活动栏中选择当前工作区里的一个 Git 仓库。
• 已跟踪变更默认选中，未跟踪文件默认不选中。
• 按文件选择提交范围，支持批量选择或取消已跟踪、未跟踪分组。
• 打开文件变更，提交所选文件，或提交后立即推送。
• 将已选择的未跟踪普通文件二次确认后移入系统废纸篓。
• 当前分支没有上游时，从已有远程中选择一个，并为同名分支建立上游。
• 修改已有远程的 fetch URL；含凭据的 URL 不会被自动回填或明文展示。
• 推送失败时保留已创建提交的哈希，可重试推送且不会重复提交。
• 当前变更按状态和目录分组，文件类型图标与 Git 状态分别展示。
• 提交历史在单行中展示摘要、作者、相对时间、短哈希和本地/远程引用；展开后可查看文件并打开历史差异。
• 显示本地 HEAD、上游引用和领先/落后数量，支持远程刷新、按仓库配置拉取以及推送全部本地领先提交。
• 使用 VS Code Language Model API 为已勾选文件生成三档密度的中文提交信息，不需要配置 Gitool API Key。
• 活动栏徽标显示当前仓库的全部变更文件数。

安装

1. 获取 gitool-file-commit-0.2.0.vsix。
2. 在桌面版 VS Code 中打开“扩展”视图。
3. 在扩展视图右上角菜单中选择“从 VSIX 安装…”。
4. 选择 VSIX，按提示重新加载窗口。

也可以在终端执行：

code --install-extension gitool-file-commit-0.2.0.vsix

使用

1. 在 VS Code 中打开一个包含 Git 仓库的工作区。
2. 点击活动栏中的 Gitool 图标，打开“文件提交”视图。
3. 工作区有多个仓库时，通过提交信息标题栏中的仓库选择器选择一个仓库；单仓库时该选择器自动隐藏。
4. 在“当前变更”中按文件勾选提交范围。三个功能区均可折叠，分隔线可拖动、用方向键调整或双击复位。
5. 输入提交信息，或在用户主动点击后使用“AI 生成”并选择精简、标准或详细密度。
6. 选择“仅提交”或“提交并推送”。
7. 在“提交历史”中查看本地和远程位置；点击提交可展开文件，点击文件可打开该提交与第一父提交之间的差异。

未跟踪文件是安全敏感范围，默认始终不提交。刷新不会自动选中未跟踪文件，必须由用户手动勾选。舍弃功能也只处理当前已选择的未跟踪普通文件，确认后通过操作系统废纸篓删除，不使用不可恢复的 Git 清理命令。

对 Git 暂存区的影响

Gitool 以完整文件为提交粒度，不提供文件内代码块选择。提交时只把所选路径写入新提交：

• 所选文件的完整当前内容进入提交，不区分该文件原先已暂存和未暂存的部分。
• 未选文件原有的暂存内容继续保留在暂存区。
• 所选未跟踪文件会在提交事务内临时加入索引；提交失败时会恢复该临时索引状态。
• 提交完成后会核对实际提交路径，防止提交范围偏离选择。

因此，在同一个文件内已有部分暂存内容时，勾选该文件代表提交该文件的完整当前内容。

推送和远程

“提交并推送”先创建本地提交，再执行推送：

• 当前分支已有上游时，推送到该上游。
• 当前分支没有上游时，只能从仓库已有远程中选择；Gitool 推送同名分支并建立上游。
• Gitool 不创建或删除远程。
• “修改远程 URL”只修改所选已有远程的 fetch URL，并在写入后核对结果。
• 游离 HEAD 状态允许本地提交，但拒绝“提交并推送”。
• 推送失败不会回滚已经创建的本地提交。界面会显示提交哈希和“重试推送”，重试使用该精确提交，不会再次提交。
• “从远程拉取”调用 VS Code 内置 Git 的标准拉取，不覆盖仓库已有的 rebase、merge 等拉取配置。
• “刷新远程状态”只获取远程引用，不合并工作区代码。
• “推送全部”使用标准非强制推送，将当前分支所有尚未同步的本地提交推送到上游；分支落后或发生分歧时会先拒绝推送。

AI 提交信息

AI 生成只在用户点击按钮后调用 VS Code 当前可用的语言模型，并由 VS Code 负责显示原生授权提示。Gitool 不要求用户填写独立 API Key，也不会自行连接第三方模型端点。

• 只读取当前已勾选文件，未勾选文件不会进入提示上下文。
• 精简模式只生成标题；标准模式生成标题和关键变化；详细模式补充行为及兼容影响。
• 二进制内容不会发送；单文件和总上下文均有限制，超出部分会明确标记或排除。
• 没有可用模型、用户未授权、模型受限或请求取消时，界面会给出中文状态，手写提交信息仍可正常使用。

工作区信任和运行环境

未受信任工作区只允许查看状态，提交、推送、舍弃和修改远程 URL 等写操作会被服务层拒绝。授予工作区信任后，Gitool 会立即刷新。

Gitool 依赖桌面版 VS Code 的内置 Git 扩展、Node.js 扩展宿主和本地 Git 命令，不支持浏览器版 VS Code。如果内置 Git 扩展缺失或被禁用，侧边栏会显示明确错误，不会执行 Git 操作。AI 功能还需要 VS Code 中存在可供扩展调用的语言模型；这不会影响手写提交信息及其他 Git 功能。

本地开发

要求 Node.js 22、npm 和 Git。

npm ci
npm run typecheck
npm run lint
npm test
npm run build
npm run test:vscode
npm run package

常用命令：

• npm run clean：清理构建产物。
• npm run check：依次执行类型检查、Lint 和 Vitest。
• npm run build：构建扩展入口和 Webview 客户端。
• npm run test:vscode：下载或复用隔离的 VS Code Electron，并运行 Extension Host 测试。
• npm run prepare:vscode-gui：创建不会自动删除的隔离双仓库工作区，并输出 Extension Development Host 启动命令和安全清理命令，供人工界面与系统废纸篓验收。
• npm run cleanup:vscode-gui -- <验收根目录>：只允许清理系统临时目录直属的 gt-g-* 或 gitool-gui-* 隔离验收根目录。
• npm run package：验证、构建并生成单个 VSIX。

Extension Host 测试会使用 Node.js tmpdir() 返回的系统临时目录，结束后自动清理；不会安装到用户正式 VS Code。macOS 使用更短的 gt-u-*、gt-e-* 和 gt-a-* 前缀，避免 Electron 主进程 Unix socket 超过系统路径长度限制。Linux 和 Windows 使用各自的系统临时目录和可读的 gitool-* 前缀；测试要求该临时目录可写，并允许启动桌面版 VS Code Electron。