Back to Details

analyzing-git-sessions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Analyzing Git Sessions

Git会话分析

Core Responsibility

核心职责

Generate structured analysis of git activity for specified timeframe or commit range, including commit history, file changes, statistics, and optional diffs.
针对指定时间段或提交范围生成Git活动的结构化分析报告，包括提交历史、文件变更、统计数据及可选的差异内容。

Inputs

输入参数

Accept from user:
  • Time range: "last 2 hours", "since 10am", "today", "since 2025-10-23 14:00"
  • Commit range: "abc123..def456", "HEAD~5..HEAD", "feature-branch..main"
  • Optional filters: Specific paths, authors, or file types
  • Output depth: Concise (default), Detailed, or Code Review format
接收用户提供的以下信息：
  • 时间范围："最近2小时"、"自上午10点起"、"今天"、"自2025-10-23 14:00起"
  • 提交范围："abc123..def456"、"HEAD~5..HEAD"、"feature-branch..main"
  • 可选过滤器：特定路径、作者或文件类型
  • 输出深度：简洁版（默认）、详细版或代码评审格式

Working Process

工作流程

Step 1: Parse and Validate Input

步骤1：解析并验证输入

  1. Determine range type:
    • Time-based: Parse relative or absolute time
    • Commit-based: Validate commit references exist
    • Branch-based: Resolve branch names to commits
  2. Validate git repository:
    bash
    git rev-parse --git-dir
  3. Check range has commits:
    bash
    git log <range> --oneline | head -1
    If empty, inform user and exit.
  1. 确定范围类型：
    • 基于时间：解析相对或绝对时间
    • 基于提交：验证提交引用是否存在
    • 基于分支：将分支名解析为对应的提交
  2. 验证Git仓库：
    bash
    git rev-parse --git-dir
  3. 检查范围内是否有提交：
    bash
    git log <range> --oneline | head -1
    若无提交，则告知用户并终止流程。

Step 2: Extract Commit History

步骤2：提取提交历史

bash
undefined
bash
undefined

Get all commits in range

获取范围内的所有提交

git log <range> --oneline --no-decorate
git log <range> --oneline --no-decorate

Get detailed commit info

获取详细提交信息

git log <range> --format="%h|%an|%ar|%s" --no-decorate
git log <range> --format="%h|%an|%ar|%s" --no-decorate

Count commits

统计提交数量

git log <range> --oneline | wc -l

Store commit data for summary.
git log <range> --oneline | wc -l

存储提交数据用于生成总结。

Step 3: Generate Statistics

步骤3：生成统计数据

Overall change statistics:
bash
undefined
整体变更统计：
bash
undefined

Summary stats (insertions/deletions by file)

摘要统计（按文件统计插入/删除行数）

git diff <start>..<end> --stat
git diff <start>..<end> --stat

Numeric stats for parsing

用于解析的数值统计

git diff <start>..<end> --numstat
git diff <start>..<end> --numstat

Count total changes

统计总变更量

git diff <start>..<end> --shortstat

**Author breakdown** (if multiple authors):

```bash
git shortlog <start>..<end> -sn
File categorization:
  • Identify new files (show in status "A")
  • Identify deleted files (show in status "D")
  • Identify renamed files (show in status "R")
  • Modified files with change magnitude
git diff <start>..<end> --shortstat

**作者细分**（若存在多位作者）：

```bash
git shortlog <start>..<end> -sn
文件分类：
  • 识别新增文件（状态显示为"A"）
  • 识别删除文件（状态显示为"D"）
  • 识别重命名文件（状态显示为"R"）
  • 标记有变更幅度的修改文件

Step 4: Identify Key Files for Detailed Analysis

步骤4：筛选需详细分析的关键文件

Prioritization rules:
  1. Large changes (>100 lines modified): Always include
  2. New files: Include (especially if >50 lines)
  3. Deleted files: Note but don't diff
  4. Architecture files: 
    build.gradle.kts
    , 
    AndroidManifest.xml
    , module configs
  5. Test files: Flag separately for test coverage assessment
Extract key file list:
bash
undefined
优先级规则：
  1. 大幅变更（修改行数>100）：始终纳入
  2. 新增文件：纳入（尤其是行数>50的文件）
  3. 删除文件：仅记录，不生成差异内容
  4. 架构文件：
    build.gradle.kts
    、
    AndroidManifest.xml
    、模块配置文件
  5. 测试文件：单独标记用于测试覆盖率评估
提取关键文件列表：
bash
undefined

Files changed with line counts

获取带行数统计的变更文件

git diff <start>..<end> --numstat | sort -rn -k1 -k2

Limit to top 10 files by default to avoid context overflow.
git diff <start>..<end> --numstat | sort -rn -k1 -k2

默认限制为前10个文件，避免上下文过载。

Step 5: Generate Selective Diffs (Based on Depth)

步骤5：根据输出深度生成选择性差异内容

Concise mode: No diffs, stats only
Detailed mode: Diffs for top 3-5 key files
bash
git diff <start>..<end> -- path/to/key/file.kt
Code Review mode: Diffs for all modified files, grouped by module
bash
undefined
简洁模式：仅展示统计数据，不包含差异内容
详细模式：展示前3-5个关键文件的差异
bash
git diff <start>..<end> -- path/to/key/file.kt
代码评审模式：展示所有修改文件的差异，按模块分组
bash
undefined

Group by directory

按目录分组

git diff <start>..<end> --name-only | cut -d'/' -f1-2 | sort -u
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

**Context overflow protection**:

- If >10 files changed significantly, limit to top 5 diffs
- Warn user: "Showing top 5 files by change size. Request specific files for full diffs."
for module in modules; do git diff <start>..<end> -- $module/ done

**上下文过载防护**：

- 若超过10个文件发生显著变更，仅展示前5个文件的差异
- 向用户提示："当前展示按变更量排序的前5个文件。如需完整差异，请指定具体文件。"

Step 6: Present Structured Summary

步骤6：呈现结构化总结

Format based on depth:
根据输出深度选择格式：

Concise Summary

简洁总结

markdown
undefined
markdown
undefined

Git Session Summary

Git会话总结

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
范围：<起始提交> 至 <结束提交>（<时间段>） 提交数：X次提交，来自Y位作者 文件变更：A个修改，B个新增，C个删除 净变更：+X行 -Y行

Commits

提交记录

  • abc123 Commit message 1
  • def456 Commit message 2 ...
  • abc123 提交信息1
  • def456 提交信息2 ...

Top Files Changed

变更量Top文件

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

Detailed Summary

详细总结

Includes:
  • Full commit list with authors and timestamps
  • Complete file list with change stats
  • Author breakdown
  • Top 3-5 diffs for review
包含：
  • 完整的提交列表（含作者和时间戳）
  • 带变更统计的完整文件列表
  • 作者贡献细分
  • 供评审的前3-5个文件差异

Code Review Format

代码评审格式

markdown
undefined
markdown
undefined

Code Review Summary

代码评审总结

Overview

概览

  • PR Title: [Suggested from commit messages]
  • Changes: X files across Y modules
  • Scope: [Inferred from changed files]
  • PR标题：[从提交信息中提取建议]
  • 变更：Y个模块中的X个文件
  • 范围：[从变更文件推断]

Commits

提交记录

[Formatted commit list suitable for PR description]
[适用于PR描述的格式化提交列表]

Changes by Module

按模块划分的变更

Module: app
  • file1.kt: Description of changes
  • file2.kt: Description of changes
Module: core ...
模块：app
  • file1.kt：变更描述
  • file2.kt：变更描述
模块：core ...

Key Changes

关键变更

[Diffs for significant modifications]
[显著修改的差异内容]

Test Coverage

测试覆盖率

  • Test files modified: X
  • New tests added: ~Y
undefined
  • 修改的测试文件：X个
  • 新增的测试用例：约Y个
undefined

Output Guidelines

输出规范

Commit Messages

提交信息

  • Show short hash (7 chars)
  • Show first line of commit message only
  • Truncate long messages to 80 chars
  • Group by author if multiple contributors
  • 显示短哈希值（7位字符）
  • 仅显示提交信息的第一行
  • 过长信息截断至80字符
  • 若有多位贡献者，按作者分组展示

File Paths

文件路径

  • Use relative paths from repo root
  • Format as code: 
    path/to/file.kt
  • Include line change magnitude: (+X -Y)
  • Highlight file type (source, test, config)
  • 使用仓库根目录的相对路径
  • 以代码格式展示：
    path/to/file.kt
  • 包含行变更幅度：(+X -Y)
  • 高亮文件类型（源码、测试、配置）

Statistics

统计数据

Present in clear tables:
markdown
| Metric        | Count |
| ------------- | ----- |
| Commits       | 15    |
| Files Changed | 23    |
| Insertions    | +450  |
| Deletions     | -180  |
以清晰的表格形式呈现：
markdown
| 指标          | 数量 |
| ------------- | ----- |
| 提交数        | 15    |
| 文件变更数    | 23    |
| 插入行数      | +450  |
| 删除行数      | -180  |

Diffs

差异内容

  • Include file path as header: 
    ### path/to/file.kt
  • Use code blocks with syntax highlighting
  • Show context lines (git default: 3 lines before/after)
  • Truncate very large diffs (>200 lines) with summary
  • 以文件路径作为标题：
    ### path/to/file.kt
  • 使用带语法高亮的代码块
  • 显示上下文行（Git默认：前后各3行）
  • 过长差异（>200行）截断并附摘要

Context Budget Management

上下文容量管理

Monitor diff sizes:
  • Small session (<10 files, <500 lines): Safe for detailed mode
  • Medium session (10-30 files, 500-2000 lines): Use selective diffs
  • Large session (>30 files, >2000 lines): Concise mode with warnings
Progressive disclosure:
  1. Always start with concise summary
  2. Ask user: "Would you like detailed diffs for specific files?"
  3. Generate diffs on demand rather than upfront
Fallback for large sessions: "This session modified 45 files with 5000+ line changes. Showing concise summary. Request specific files or modules for detailed diffs."
监控差异大小：
  • 小型会话（<10个文件，<500行变更）：适合详细模式
  • 中型会话（10-30个文件，500-2000行变更）：使用选择性差异
  • 大型会话（>30个文件，>2000行变更）：使用简洁模式并提示
渐进式披露：
  1. 始终先展示简洁总结
  2. 询问用户："是否需要查看特定文件的详细差异？"
  3. 根据需求生成差异，而非预先全部生成
大型会话的 fallback 方案： "本次会话修改了45个文件，涉及5000+行变更。当前展示简洁总结。如需详细差异，请指定具体文件或模块。"

Anti-Patterns to Avoid

需避免的反模式

Don't:
  • Generate diffs for all files in large sessions (context overflow)
  • Include full diffs without asking (waste context on unneeded details)
  • Ignore file types (treat test changes same as source changes)
  • Lose context on what user wants to know
  • Use generic summaries ("modified 10 files") without specifics
Do:
  • Ask user what level of detail they need
  • Prioritize key files by change magnitude
  • Categorize files (source, test, config, docs)
  • Provide actionable summaries
  • Offer to drill down on specific files
请勿：
  • 为大型会话生成所有文件的差异（导致上下文过载）
  • 未询问用户就生成完整差异（浪费上下文在不必要的细节上）
  • 忽略文件类型（将测试变更与源码变更同等对待）
  • 丢失用户的核心需求上下文
  • 使用通用总结（如"修改了10个文件"）而不提供具体信息
建议：
  • 询问用户所需的详细程度
  • 按变更幅度优先展示关键文件
  • 对文件进行分类（源码、测试、配置、文档）
  • 提供可操作的总结
  • 支持用户深入查看特定文件

Success Criteria

成功标准

A good git session analysis should:
  1. Inform: User understands scope of changes at a glance
  2. Focus: Highlights most significant changes first
  3. Actionable: Provides paths and diffs for deeper review
  4. Efficient: Doesn't waste context on unnecessary details
  5. Adaptable: Adjusts depth based on session size and user needs
一份优质的Git会话分析应满足：
  1. 信息明确：用户一眼就能了解变更范围
  2. 重点突出：优先展示最显著的变更
  3. 可操作：提供路径和差异内容供深入评审
  4. 高效：不浪费上下文在不必要的细节上
  5. 适应性强：根据会话规模和用户需求调整输出深度

Example Outputs

示例输出

See 
contexts/example-outputs.md
for detailed examples of concise summaries and code review formats.
详见
contexts/example-outputs.md
，包含简洁总结和代码评审格式的详细示例。