Git 工具

AggRoot 提供 13 个 Git 操作工具，覆盖日常版本控制全部流程。核心原则：始终使用 Git 工具，而非 Shell 执行 git 命令。

工具一览

工具	说明	风险等级
GitStatus	查看工作区状态	safe
GitDiff	查看代码差异	safe
GitLog	查看提交历史	safe
GitShow	查看提交详情	safe
GitBranch	管理分支（列出/创建/删除）	medium
GitCheckout	切换分支或恢复文件	medium
GitRemote	管理远程仓库	medium
GitStash	暂存/恢复更改	medium
GitAdd	添加文件到暂存区	medium
GitCommit	提交更改	dangerous
GitPush	推送到远程仓库	dangerous
GitPull	拉取远程代码	medium
GitRepoFetch	获取远程仓库概览/目录/文件	safe

GitStatus — 查看状态

查看工作区文件状态（修改、新增、删除、未追踪）。

参数

参数	类型	必填	说明
path	string	否	仓库路径（默认当前目录）

示例

GitStatus({})
GitStatus({"path": "/projects/my-app"})

GitDiff — 查看差异

查看工作区或暂存区的文件修改差异。

参数

参数	类型	必填	说明
path	string	否	仓库路径
staged	boolean	否	显示暂存区差异（默认 false）
file	string	否	指定查看差异的文件

示例

// 查看所有未暂存的修改
GitDiff({})

// 查看暂存区的修改
GitDiff({"staged": true})

// 查看特定文件的差异
GitDiff({"file": "src/app.ts"})

GitLog — 查看历史

查看提交历史记录。

参数

参数	类型	必填	默认值	说明
path	string	否	—	仓库路径
count	number	否	10	显示的提交数量
oneline	boolean	否	false	单行显示模式

示例

// 查看最近 10 条提交
GitLog({})

// 查看最近 5 条（单行模式）
GitLog({"count": 5, "oneline": true})

// 查看更多历史
GitLog({"count": 30})

GitShow — 查看提交详情

查看指定提交的详细内容，包括修改的文件和具体差异。

参数

参数	类型	必填	说明
object	string	是	提交哈希、标签名或分支名
path	string	否	仓库路径
format	string	否	输出格式：`full`（默认）、`stat`（统计）、`name-only`（仅文件名）

示例

// 查看提交详情
GitShow({"object": "a1b2c3d"})

// 仅查看修改的文件列表
GitShow({"object": "a1b2c3d", "format": "name-only"})

// 查看统计信息
GitShow({"object": "HEAD", "format": "stat"})

GitBranch — 管理分支

列出、创建或删除分支。

参数

参数	类型	必填	说明
path	string	否	仓库路径
create	string	否	创建指定名称的分支
delete	string	否	删除指定名称的分支

不带 create 和 delete 参数时列出所有分支。

示例

// 列出所有分支
GitBranch({})

// 创建新分支
GitBranch({"create": "feature/login"})

// 删除分支
GitBranch({"delete": "feature/old-branch"})

GitCheckout — 切换分支

切换分支、创建并切换到新分支、或恢复文件。

参数

参数	类型	必填	说明
path	string	否	仓库路径
branch	string	否	要切换到的分支名
createBranch	string	否	创建并切换到此分支
file	string	否	从 HEAD 恢复指定文件

示例

// 切换到已有分支
GitCheckout({"branch": "main"})

// 创建并切换到新分支
GitCheckout({"createBranch": "feature/api"})

// 恢复文件到 HEAD 版本
GitCheckout({"file": "src/app.ts"})

GitRemote — 管理远程仓库

查看、添加、删除或修改远程仓库配置。

参数

参数	类型	必填	说明
path	string	否	仓库路径
action	string	否	操作：`list`（默认）、`add`、`remove`、`set-url`
name	string	否	远程仓库名（如 origin）
url	string	否	远程仓库 URL（add/set-url 时需要）

示例

// 列出远程仓库
GitRemote({})

// 添加远程仓库
GitRemote({"action": "add", "name": "origin", "url": "https://your-git-host.com/owner/repo.git"})

// 修改远程仓库 URL
GitRemote({"action": "set-url", "name": "origin", "url": "https://your-git-host.com/owner/new-repo.git"})

// 删除远程仓库
GitRemote({"action": "remove", "name": "upstream"})

GitStash — 暂存更改

临时保存或恢复工作区更改。

参数

参数	类型	必填	说明
path	string	否	仓库路径
action	string	否	操作：`push`（默认）、`pop`、`apply`、`list`、`drop`
message	string	否	暂存说明（push 时使用）
index	number	否	暂存索引（pop/apply/drop 时使用，默认 0）

示例

// 暂存当前更改
GitStash({"action": "push", "message": "WIP: 登录功能"})

// 查看暂存列表
GitStash({"action": "list"})

// 恢复最近的暂存
GitStash({"action": "pop"})

// 恢复指定暂存（保留暂存记录）
GitStash({"action": "apply", "index": 1})

// 删除指定暂存
GitStash({"action": "drop", "index": 2})

GitAdd — 添加到暂存区

将文件添加到 Git 暂存区。

参数

参数	类型	必填	说明
path	string	否	仓库路径
files	string	否	文件路径（默认 `.` 添加全部），支持 glob 模式

示例

// 添加所有文件
GitAdd({})

// 添加指定文件
GitAdd({"files": "src/app.ts"})

// 添加多个文件
GitAdd({"files": "src/app.ts src/utils.ts"})

// 使用 glob 模式
GitAdd({"files": "src/**/*.test.ts"})

GitCommit — 提交更改

提交暂存区的更改。

参数

参数	类型	必填	说明
path	string	否	仓库路径
message	string	是	提交信息

提交信息验证

支持自然语言（包括中文）
允许括号 ()、引号 ""/''、连字符 -
阻止命令注入（;、&、|、反引号、$() 等）
最大长度 4096 字符

示例

// 中文提交信息
GitCommit({"message": "修复登录页面样式问题"})

// 带括号的提交信息
GitCommit({"message": "feat(auth): 添加 OAuth2 登录支持"})

// 常规格式
GitCommit({"message": "fix: resolve null pointer in handler"})

GitPush — 推送代码

将本地提交推送到远程仓库。

参数

参数	类型	必填	说明
path	string	否	仓库路径
remote	string	否	远程仓库名（默认 origin）
branch	string	否	分支名

示例

// 推送到 origin
GitPush({})

// 推送到指定远程和分支
GitPush({"remote": "origin", "branch": "main"})

GitPull — 拉取代码

从远程仓库拉取并合并代码。

参数

参数	类型	必填	说明
path	string	否	仓库路径
remote	string	否	远程仓库名（默认 origin）
branch	string	否	分支名

示例

// 拉取并合并
GitPull({})

// 拉取指定远程分支
GitPull({"remote": "upstream", "branch": "main"})

GitRepoFetch — 获取远程仓库

获取 Git 托管平台的项目代码，用于学习开源项目的设计和实现。

参数

参数	类型	必填	说明
url	string	是	Git 仓库 URL
mode	string	否	模式：`overview`（概览）、`tree`（目录）、`file`（文件）。默认自动判断
depth	number	否	目录深度（默认 2）
maxFiles	number	否	最大文件数（默认 20）
maxSize	number	否	最大文件大小 KB（默认 50）

支持的 URL 格式

完整 URL：https://your-git-host.com/owner/repo
带路径：https://your-git-host.com/owner/repo/tree/main/src
文件 URL：https://your-git-host.com/owner/repo/blob/main/README.md
简写格式：owner/repo

示例

// 项目概览（README + 目录 + 主要文件）
GitRepoFetch({"url": "https://your-git-host.com/owner/repo"})

// 浏览特定目录
GitRepoFetch({"url": "https://your-git-host.com/owner/repo/tree/main/packages"})

// 获取特定文件
GitRepoFetch({"url": "https://your-git-host.com/owner/repo/blob/main/README.md"})

// 使用简写
GitRepoFetch({"url": "owner/repo"})

常见工作流

1. 检查状态并提交

// 1. 查看修改
GitStatus({})
GitDiff({})

// 2. 添加文件
GitAdd({"files": "src/app.ts"})

// 3. 提交
GitCommit({"message": "feat: 添加用户登录功能"})

2. 推送到远程

GitPush({"remote": "origin", "branch": "feature/login"})

3. 分支管理

// 创建并切换到新分支
GitCheckout({"createBranch": "feature/api"})

// 完成开发后切回主分支
GitCheckout({"branch": "main"})

// 删除功能分支
GitBranch({"delete": "feature/api"})

4. 暂存和恢复

// 临时保存工作
GitStash({"action": "push", "message": "WIP"})

// 切换分支处理紧急任务
GitCheckout({"branch": "hotfix/bug"})

// 处理完毕后恢复
GitCheckout({"branch": "feature/api"})
GitStash({"action": "pop"})

5. 学习开源项目

// 获取项目概览
GitRepoFetch({"url": "owner/repo"})

// 深入查看目录
GitRepoFetch({"url": "owner/repo", "mode": "tree", "depth": 3})

// 查看具体文件
GitRepoFetch({"url": "owner/repo", "mode": "file"})

安全机制

所有 Git 工具内置安全防护：

路径验证：阻止路径遍历（..）和 Shell 元字符注入
命令注入防护：分支名、提交信息等参数经过严格验证
环境变量隔离：子进程使用安全环境变量，防止 API Key 泄漏
超时保护：所有 Git 命令 60 秒超时，防止挂起
进程树清理：超时后完整终止进程组（含子进程）

← 上一篇

代码工具

Shell 工具