analyzing-git-sessions

分析 Git 会话

核心职责

针对指定时间范围或提交范围，生成 Git 活动的结构化分析，包括提交历史、文件更改、统计数据和可选的差异。

输入

接受用户提供的：

• 时间范围：“最近 2 小时”“从上午 10 点起”“今天”“从 2025-10-23 14:00 起”
• 提交范围：“abc123..def456”“HEAD~5..HEAD”“feature-branch..main”
• 可选筛选条件：特定路径、作者或文件类型
• 输出深度：简洁（默认）、详细或代码审查格式

工作流程

步骤 1：解析并验证输入

1. 确定范围类型：

   • 基于时间：解析相对或绝对时间
   • 基于提交：验证提交引用是否存在
   • 基于分支：将分支名称解析为提交

2. 验证 Git 仓库：

   git rev-parse --git-dir
   

3. 检查范围内是否有提交：

   git log <range> --oneline | head -1
   

   如果为空，告知用户并退出。

步骤 2：提取提交历史

# Get all commits in range
git log <range> --oneline --no-decorate

# Get detailed commit info
git log <range> --format="%h|%an|%ar|%s" --no-decorate

# Count commits
git log <range> --oneline | wc -l

保存提交数据以供汇总。

步骤 3：生成统计数据

整体更改统计：

# Summary stats (insertions/deletions by file)
git diff <start>..<end> --stat

# Numeric stats for parsing
git diff <start>..<end> --numstat

# Count total changes
git diff <start>..<end> --shortstat

作者细分（如果有多位作者）：

git shortlog <start>..<end> -sn

文件分类：

• 识别新增文件（状态显示为“A”）
• 识别已删除文件（状态显示为“D”）
• 识别重命名文件（状态显示为“R”）
• 列出已修改文件及其更改幅度

步骤 4：确定需要详细分析的关键文件

优先级规则：

1. 大幅更改（修改超过 100 行）：始终包含
2. 新增文件：包含（尤其是超过 50 行的文件）
3. 已删除文件：注明，但不显示差异
4. 架构文件：build.gradle.kts、AndroidManifest.xml、模块配置
5. 测试文件：单独标记，以便评估测试覆盖率

提取关键文件列表：

# Files changed with line counts
git diff <start>..<end> --numstat | sort -rn -k1 -k2

默认最多列出前 10 个文件，以避免上下文溢出。

步骤 5：生成选择性差异（根据深度）

简洁模式：不显示差异，仅显示统计数据

详细模式：显示排名前 3–5 个关键文件的差异

git diff <start>..<end> -- path/to/key/file.kt

代码审查模式：按模块分组，显示所有已修改文件的差异

# Group by directory
git diff <start>..<end> --name-only | cut -d'/' -f1-2 | sort -u

# Generate diffs per module
for module in modules; do
  git diff <start>..<end> -- $module/
done

上下文溢出保护：

• 如果有超过 10 个文件发生重大更改，将差异限制为前 5 个文件
• 提醒用户：“正在显示按更改规模排名前 5 的文件。如需查看完整差异，请指定文件。”

步骤 6：呈现结构化摘要

根据深度选择格式：

简洁摘要

## Git Session Summary

**Range**: <start-commit> to <end-commit> (<timeframe>)
**Commits**: X commits by Y author(s)
**Files Changed**: A modified, B added, C deleted
**Net Changes**: +X -Y lines

### Commits

- abc123 Commit message 1
- def456 Commit message 2
  ...

### Top Files Changed

1. path/to/file1.kt (+50 -20)
2. path/to/file2.kt (+30 -15)
   ...

详细摘要

包括：

• 完整提交列表，以及作者和时间戳
• 完整文件列表及更改统计
• 作者细分
• 排名前 3–5 个文件的差异，供审查

代码审查格式

## Code Review Summary

### Overview

- **PR Title**: [Suggested from commit messages]
- **Changes**: X files across Y modules
- **Scope**: [Inferred from changed files]

### Commits

[Formatted commit list suitable for PR description]

### Changes by Module

**Module: app**

- file1.kt: Description of changes
- file2.kt: Description of changes

**Module: core**
...

### Key Changes

[Diffs for significant modifications]

### Test Coverage

- Test files modified: X
- New tests added: ~Y

输出指南

提交消息

• 显示短哈希（7 个字符）
• 仅显示提交消息的第一行
• 将较长的消息截断至 80 个字符
• 如果有多位贡献者，按作者分组

文件路径

• 使用相对于仓库根目录的路径
• 使用代码格式：path/to/file.kt
• 包含行更改幅度：（+X -Y）
• 标明文件类型（源代码、测试、配置）

统计数据

使用清晰的表格呈现：

| Metric        | Count |
| ------------- | ----- |
| Commits       | 15    |
| Files Changed | 23    |
| Insertions    | +450  |
| Deletions     | -180  |

差异

• 将文件路径作为标题包含在内：### path/to/file.kt
• 使用带语法高亮的代码块
• 显示上下文行（Git 默认值：前后各 3 行）
• 对非常大的差异（超过 200 行）进行截断并附上摘要

上下文预算管理

监控差异大小：

• 小型会话（少于 10 个文件，少于 500 行）：适合使用详细模式
• 中型会话（10–30 个文件，500–2000 行）：使用选择性差异
• 大型会话（超过 30 个文件，超过 2000 行）：使用简洁模式并发出警告

渐进式展示：

1. 始终从简洁摘要开始
2. 询问用户：“您想查看特定文件的详细差异吗？”
3. 按需生成差异，而不是预先生成

大型会话的回退方案： “此会话修改了 45 个文件，更改超过 5000 行。现显示简洁摘要。如需查看详细差异，请指定文件或模块。”

应避免的反模式

不要：

• 在大型会话中为所有文件生成差异（会导致上下文溢出）
• 未经询问就包含完整差异（会浪费上下文，展示不必要的细节）
• 忽略文件类型（将测试变更与源代码变更一视同仁）
• 忘记用户想了解的内容
• 使用泛泛的摘要（例如“修改了 10 个文件”），却不提供具体信息

应该：

• 询问用户需要什么详细程度
• 根据变更幅度优先展示关键文件
• 对文件进行分类（源代码、测试、配置、文档）
• 提供可采取行动的摘要
• 提供针对特定文件进一步深入分析的选项

成功标准

良好的 git 会话分析应做到：

1. 告知：让用户一目了然地了解变更范围
2. 聚焦：优先突出最重要的变更
3. 可采取行动：提供路径和差异，便于深入审查
4. 高效：不在不必要的细节上浪费上下文
5. 灵活调整：根据会话规模和用户需求调整分析深度

输出示例

请参阅 contexts/example-outputs.md，了解简明摘要和代码审查格式的详细示例。