Back to Details

review-history

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Review History

代码历史分析

Investigate how code evolved over time to understand current behavior or find regressions.
调查代码随时间的演变过程，以理解当前行为或定位回归问题。

Usage

使用方式

/review-history src/auth/login.ts
/review-history the authentication flow
/review-history UserProfile component
/review-history src/auth/login.ts
/review-history the authentication flow
/review-history UserProfile component

Workflow

工作流程

Step 1: Identify Target Files

步骤1：确定目标文件

From the provided topic, identify the relevant files:
  • If a file path is given, use it directly
  • If a feature/function name, locate relevant files using this strategy:
    1. Grep for the exact function/class name to find where it is defined and used
    2. Glob for files with the feature name in the path (e.g., 
      **/*payment*
      )
    3. Prioritize source files over test files; include tests only if investigating test behavior
    4. Limit to the 5 most relevant files to keep the analysis focused
根据提供的主题，确定相关文件：
  • 如果提供了文件路径，直接使用该路径
  • 如果是功能/函数名称，使用以下策略定位相关文件：
    1. 使用Grep搜索精确的函数/类名，找到其定义和使用的位置
    2. 使用Glob匹配路径中包含功能名称的文件（例如：
      **/*payment*
      ）
    3. 优先选择源文件而非测试文件；仅当调查测试行为时才包含测试文件
    4. 限制为最多5个最相关的文件，以保持分析的聚焦性

Step 2: Git History Analysis

步骤2：Git历史分析

Run these in parallel:
Recent commits touching the area:
bash
git log --oneline -20 -- <file_or_directory>
Detailed blame for key sections:
bash
undefined
并行执行以下操作：
涉及目标区域的近期提交：
bash
git log --oneline -20 -- <file_or_directory>
关键代码段的详细追溯：
bash
undefined

For files > 200 lines: target the specific function or section under investigation.

对于超过200行的文件：定位到正在调查的特定函数或代码段。

Use Grep to find the line range first, then:

先使用Grep找到行范围，然后执行：

git blame -L <start>,<end> <file>
git blame -L <start>,<end> <file>

For files ≤ 200 lines: blame the entire file:

对于≤200行的文件：追溯整个文件的修改历史：

git blame <file>

**Find when specific code was introduced:**
```bash
git log -S "<search_term>" --oneline -- <file>
Check for recent refactors:
bash
git log --oneline --since="3 months ago" -- <file_or_directory>
Adjust the time window based on context:
  • Investigating a recent regression: use 
    --since="2 weeks ago"
  • Understanding a feature's evolution: use 
    --since="6 months ago"
    or omit 
    --since
    entirely
  • If the initial window returns fewer than 3 commits, double the window and retry once
git blame <file>

**定位特定代码的引入时间：**
```bash
git log -S "<search_term>" --oneline -- <file>
检查近期重构：
bash
git log --oneline --since="3 months ago" -- <file_or_directory>
根据上下文调整时间范围：
  • 调查近期回归问题：使用
    --since="2 weeks ago"
  • 理解功能的演变：使用
    --since="6 months ago"
    或完全省略
    --since
    参数
  • 如果初始时间范围返回的提交少于3个，将时间范围翻倍后重试一次

Step 3: Search Past Issue Logs

步骤3：搜索过往问题日志

Check if this problem occurred before:
  1. List past issue logs:
    • Glob pattern: 
      docs/log/*.md
  2. Search logs for relevant keywords:
    • Grep pattern: 
      {keywords}
      path: 
      docs/log/
Look for:
  • Similar error messages
  • Same file/function names
  • Related symptoms
检查该问题是否曾出现过：
  1. 列出过往问题日志：
    • Glob模式：
      docs/log/*.md
  2. 使用相关关键词搜索日志：
    • Grep模式：
      {keywords}
      路径：
      docs/log/
重点查找:
  • 类似的错误信息
  • 相同的文件/函数名称
  • 相关的症状

Step 4: Synthesize Findings

步骤4：整合分析结果

Populate the report using these methods:
  • Recent Changes: List commits from 
    git log
    , most recent first. Include only commits that touch the target code.
  • Key Code Introduction: Use 
    git log -S
    results to identify when the function/feature first appeared and its last substantive change (skip formatting-only commits).
  • Related Past Issues: Direct matches from Step 3. If none found, state "None found in docs/log/".
  • Regression Risk: Compare current behavior against commit history. If code worked before a specific commit and broke after, name that commit. If no clear regression point, state "No clear regression identified — behavior may be by design."
Report:
markdown
undefined
使用以下方法生成报告：
  • 近期变更：列出
    git log
    中的提交记录，按时间从新到旧排序。仅包含涉及目标代码的提交。
  • 关键代码引入：使用
    git log -S
    的结果，确定函数/功能首次出现的时间点及其最后一次实质性变更（跳过仅格式化的提交）。
  • 相关过往问题：步骤3中找到的匹配项。如果未找到，注明“在docs/log/中未找到相关记录”。
  • 回归风险：将当前行为与提交历史进行对比。如果代码在某个特定提交前正常工作，之后出现问题，注明该提交。如果没有明确的回归点，注明“未明确识别回归点——该行为可能是设计如此。”
报告格式：
markdown
undefined

History Analysis: {target}

历史分析报告：{target}

Recent Changes

近期变更

DateCommitAuthorSummary
{date}{hash}{author}{message}
日期提交哈希作者摘要
{date}{hash}{author}{message}

Key Code Introduction

关键代码引入

  • {function/feature}
    introduced in {commit} on {date}
  • Last modified: {commit} by {author}
  • {function/feature}
    于{date}在提交{commit}中引入
  • 最后修改：{author}在提交{commit}中完成

Related Past Issues

相关过往问题

{any matching docs/log entries, or "None found"}
{匹配的docs/log条目，或“未找到相关记录”}

Regression Risk

回归风险评估

{assessment: was this working before? when did it break?}
undefined
{评估内容：之前是否正常工作？何时出现故障？}
undefined

Examples

示例

Trace when a payment bug was introduced:
/review-history processPayment
Uses 
git log -S
and 
git blame
to trace the payment processing function, identifies the commit that changed the rounding logic three weeks ago, and cross-references with past issue logs to confirm this is when the billing discrepancy started.
Understand why validation works a certain way:
/review-history src/validators/address.ts
Analyzes the git history of the address validator, surfaces the original commit that added the unusual postal code regex along with its commit message explaining a partner API requirement, and checks past issue logs for related context.
定位支付Bug的引入时间：
/review-history processPayment
使用
git log -S
和
git blame
追踪支付处理函数，识别出三周前修改了四舍五入逻辑的提交，并与过往问题日志交叉验证，确认这就是计费差异开始出现的时间点。
理解验证逻辑的设计原因：
/review-history src/validators/address.ts
分析地址验证器的Git历史，找出添加特殊邮政编码正则表达式的原始提交及其提交说明（解释了合作方API的要求），并检查过往问题日志以获取相关背景信息。

Troubleshooting

问题排查

Relevant commit was squashed or rebased away

相关提交被压缩或变基移除

Solution: Use 
git reflog
to find the original commit before the squash or rebase. If the reflog has expired, search for the change using 
git log -S "<code_snippet>" --all
to locate it in any branch or dangling commit.
解决方法： 使用
git reflog
找到压缩或变基前的原始提交。如果reflog已过期，使用
git log -S "<code_snippet>" --all
在所有分支或悬空提交中搜索该变更。

History is too large to analyze effectively

历史记录过多，无法高效分析

Solution: Narrow the scope by passing a specific file path or function name instead of a broad directory. Use 
--since
with 
git log
to limit the time window, or focus on a single author's contributions with 
--author
.
解决方法： 通过传递特定文件路径或函数名称而非宽泛的目录来缩小范围。在
git log
中使用
--since
参数限制时间范围，或使用
--author
参数聚焦于单个作者的提交。

Notes

注意事项

  • Focus on commits from the last 3-6 months unless investigating older issues
  • Pay attention to refactors, dependency updates, and merge commits
  • If a past issue log matches, read it fully - it may contain the solution
  • 除非调查旧问题，否则重点关注过去3-6个月的提交
  • 留意重构、依赖更新和合并提交
  • 如果找到匹配的过往问题日志，请完整阅读——其中可能包含解决方案