# Git 集成方案

> 调研日期：2026-04-11
> 状态：已调研，待实现

## 1. 判定 Git 仓库

从目标路径逐级向上查找 `.git` 目录：

```bash
git -C <path> rev-parse --is-inside-work-tree
# 返回 "true" = 是 git 仓库
```

Go 实现：`filepath.Walk` 向上遍历，检查 `.git` 目录存在性。

## 2. 可实现功能

| 功能 | 难度 | 命令 |
|------|------|------|
| 文件状态（修改/新增/删除/未跟踪） | 低 | `git status --porcelain=v1 <file>` |
| 文件/文件夹提交历史 | 低 | `git log --oneline -20 -- <path>` |
| 当前文件与 HEAD 的 diff | 中 | `git diff HEAD -- <file>` |
| 某行代码 blame | 低 | `git blame <file>` |
| 当前分支名 | 低 | `git branch --show-current` |

## 3. 实现架构

### Go 后端（~200 行）

```
internal/git/
├── git.go          # 核心逻辑：判定仓库、执行命令、解析输出
├── status.go       # 文件状态查询
├── history.go      # 提交历史
├── diff.go         # 文件差异
└── blame.go        # 行级追溯
```

关键接口设计：
- `IsGitRepo(path string) bool` — 判定是否为 git 仓库
- `GetFileStatus(path string) (string, error)` — 返回 M/A/D/? 状态码
- `GetFileHistory(path string, limit int) ([]Commit, error)` — 提交历史
- `GetFileDiff(path string) (string, error)` — diff 文本
- `BlameFile(path string) ([]BlameLine, error)` — blame 结果

### 前端（~100 行）

- **文件列表**：图标列增加 git 状态小标记（M=修改, A=新增, D=删除, ?=未跟踪）
- **右键菜单**：git 仓库内显示「查看历史」「查看 Diff」「Blame」等选项
- **弹窗组件**：提交历史列表 / Diff 查看 / Blame 视图

### 调用方式

Go 侧通过 `os/exec.Command("git", "-C", repoPath, ...)` 执行系统 git 命令，
解析 stdout 返回结构化数据给前端。

## 4. 前提条件

- 系统需安装 Git（Windows 上基本都有）
- 仅在有 `.git` 的目录下激活相关功能
- 大文件/二进制文件不做 diff/blame

## 5. 注意事项

- `git -C <path>` 确保 git 命令在正确仓库上下文执行
- `--porcelain=v1` 输出格式稳定，适合程序解析
- 中文路径需注意编码（UTF-8）
- 性能：避免频繁调用 git 命令，考虑缓存结果