用 git log -S 定位代码行的引入提交

改动一处代码前，常需要先回答：这行判断是什么时候加进来的、当时为什么加。仓库有几千个提交时，逐条 git log -p 翻不现实。git log -S 就是为这个问题准备的。

什么情况下会撞上它

典型场景是接手一段无注释代码，比如 if retry_count > 3:，需要知道阈值是谁定的、有没有对应需求或故障记录。反过来，某行日志突然从历史里消失，要找出删除它的提交，确认是否误删。共同点是：知道要找的文本，不知道提交。--author、--since、--grep 按元数据筛，-p 只展示不筛选，都不解决问题。

怎么做

git log -S "retry_count > 3" --oneline

输出是引入或删除过该字符串的提交列表，最新在前。拿到提交号后：

git show 4f2a1c9 -- path/to/client.py

限定文件时 -- 分隔符不能省：

git log -S "retry_count > 3" --oneline -- src/client.py

-S 默认区分大小写，忽略大小写加 -i；按正则匹配改用 -G：

git log -G "retry_count\s*>\s*[0-9]+" --oneline

要看改动内容加 -p。

为什么有效

-S 在 git 里叫 pickaxe。它不在完整 diff 里做子串搜索，而是对每个提交比较父提交与当前提交中该字符串的出现次数，次数变了就选中。因此它只关心“多了还是少了”，不关心位置移动：一行代码从文件 A 挪到 B，仍会命中。纯格式改动（缩进、换行）不改变字符串本身，不会命中；但字符串被拆行或合并，次数变了就会命中。

-G 机制不同：它对 diff 的增删行做正则匹配，只要新增或删除的行里出现匹配内容就选中。所以 -G 会命中“同一行里改了别的部分”的提交，-S 不会。排查“这行代码何时出现”用 -S 更准，排查“这个模式何时被改动”用 -G 更全。

怎么确认结果

1. git show --stat 看改动范围是否合理。
2. git show -p 确认字符串确实在这一提交里增减。
3. git log -S "..." --oneline ^.. 单独跑这一提交，排除是合并提交带进来的。

结果为空时先确认分支范围，默认只查当前分支可达历史：

git log -S "retry_count > 3" --all --oneline

仍为空则检查浅克隆：git rev-parse --is-shallow-repository 返回 true 时历史被截断，pickaxe 只能看到本地提交，需 git fetch --unshallow 补全。

边界和代价

-S 要遍历每个提交并计算出现次数，大仓库上很慢，可先用 --since 缩小时间范围或用 -- path 限定目录。文件被 git mv 重命名后字符串次数不变，不会命中，需配合 --follow 单独查文件历史。

合并提交是另一个易踩点：默认 git log 不展示合并提交的 diff，-S 对合并提交的处理依赖 --diff-merges 相关选项，不同 git 版本默认行为有差异，以当前版本 git help log 为准。排查时优先看普通提交。

最后，-S 搜的是提交内容，不是工作区。未提交的改动、.gitignore 排除的文件、子模块内部历史，都不在搜索范围内。