---
date: 2026-05-11
tags: [git, hooks, config, gotcha]
---

# `git config` 拒绝带下划线的 key — pre-push hook 用 `push.ai_check_sha` 被 invalid key 拒掉

## 现象

```bash
$ git config --local push.ai_check_sha abc123
error: invalid key: push.ai_check_sha
$ echo $?
1
```

`.githooks/pre-push` 在 AI review 自检通过后写入这个 key 做去重缓存，写失败 + `set -e` 让 hook 退 1，push 被卡。所有装了 claude CLI 又没 export `FFOA_SKIP_AI_REVIEW_LOCAL=1` 的开发机都会撞。

## 根因

Git config 的 key 语法（`man git-config`）只允许 alphanumeric + `-`，不允许 `_`。

```bash
$ git config --local push.aichecksha test   # ✅ exit=0
$ git config --local push.ai-check-sha test # ✅ exit=0
$ git config --local push.ai_check_sha test # ❌ exit=1 invalid key
```

Git 2.43 验证。

## 解决

- `.githooks/pre-push` 把 key 重命名为 camelCase `push.aiChecksha`（git config 习惯 camelCase）
- 已有的本地 `push.ai_check_sha` 残留**不会**存在（因为之前所有写入都失败了），不需要 cleanup

## 排查方法

写 hook / 脚本时如果要用 `git config` 存自定义 key：
- ✅ `section.camelCase`
- ✅ `section.with-dashes`
- ❌ `section.with_underscores`
- 写完后用 `git config --local <key> test && git config --local --unset <key>` 跑一下 sanity check

## 关联

- PR #301（feat(pr-workflow): 模板 v2 / AI Review 结构化 / 本地前置自检） 引入此 hook
- 工单 #171 转正 ai-review 时 push 被卡 → 顺手修