# git-init 参考

SKILL.md 未覆盖的细节。Agent 只在需要时阅读本文件。Gitea 见 [gitea.md](gitea.md)；克隆/拉取/分支/合并见 [workflows.md](workflows.md)。

## 中文提交规范

所有提交信息必须使用中文。

格式：

```
类型: 描述

Co-authored-by: 姓名 <邮箱>
```

每次提交**必须**带 `Co-authored-by`（Git trailer）。主体与 trailer 之间空一行。

- 默认：档案中的 `userName` / `userEmail`（例如 `Co-authored-by: 旅行呀~ <travelxiao@qq.com>`）
- 额外合作者：档案字段 `coAuthors`（`store-profile.ps1` 可追加 `Name <email>`）
- 生成完整说明：`emit-commit-message.ps1 -Subject "类型: 描述"`

示例：

```
初始化: 完成项目Git配置

Co-authored-by: 旅行呀~ <travelxiao@qq.com>
```

```
新增: 添加用户模块

Co-authored-by: 旅行呀~ <travelxiao@qq.com>
```

禁止：

```
update

fix

test

修改一下
```

后续提交作者（`git` Author）必须为本地档案中的 `姓名 <邮箱>`，且说明里含对应 `Co-authored-by`。每次提交必须包含清晰描述，例如：

```
新增: 添加支付接口

Co-authored-by: 旅行呀~ <travelxiao@qq.com>
```

签名提交使用 `git commit -S`。仓库 local 配置 `commit.gpgsign=true` 后，普通 `git commit` 也会签名。

## 日常提交

每次提交都走 `prepare-commit.ps1`，不要重新 `git init`。

1. `prepare-commit.ps1` 把档案中的 `user.name` / `user.email` 写到**当前仓库**，并打开 `commit.gpgsign`；输出 `co_authored_by=`
2. `signing=missing` 时再跑 `ensure-gpg.ps1`，写入 `user.signingkey`
3. `git status` / `git diff` / `git log -5` 后再写中文 `类型: 描述`
4. `assert-no-secrets.ps1` 失败则不得提交匹配路径
5. 后续提交只暂存相关文件，不要默认 `git add -A`
6. 用 `emit-commit-message.ps1` 生成带 `Co-authored-by` 的说明，再 `git commit -S -m ...`
7. `git log -1 --format=%B` 确认含 `Co-authored-by:`
8. 用户没说推送就不要 `git push`

无变更时不要空提交。

## 日常推送

每次推送都走 `prepare-push.ps1`，不要重新初始化。

1. 从 `origin` 解析 URL；HTTPS 静默注入 Token；SSH 则 `ssh-add`（不生成新密钥、不打印公钥）
2. 当前分支无上游：`git push -u origin HEAD`
3. 已有上游：`git push`
4. 禁止 `--force`，除非用户明确要求
5. URL 里若带账号密码，脚本输出会打码，Agent 也不得把完整带密 URL 发到对话里

## Windows SSH

不要使用：

```bash
eval "$(ssh-agent -s)"
```

Windows 使用 OpenSSH 服务：

```powershell
Get-Service ssh-agent
Set-Service ssh-agent -StartupType Manual
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519
```

`ensure-ssh.ps1` 会尝试启动服务并 `ssh-add`。`Set-Service` / `Start-Service` 在服务被禁用时可能需要管理员权限；失败时仍展示公钥，让用户手动添加。

公钥路径：`<private-key>.pub`。只把公钥贴到 **Gitea → 设置 → SSH / GPG 密钥**。私钥不得出现在聊天或仓库里。

测试（推荐脚本，支持自建端口）：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/test-ssh.ps1" -RemoteUrl "git@git.example.com:owner/repo.git"
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/test-ssh.ps1" -RemoteUrl "ssh://git@git.example.com:2222/owner/repo.git"
```

手写等价命令：

```powershell
ssh -T git@git.example.com
ssh -p 2222 -T git@git.example.com
```

Gitea 成功时常见输出含 `Hi there` / `successfully authenticated` / `Welcome to Gitea`，退出码可能为 1。无 shell 权限是正常的。

完整菜单与 Token 步骤见 [gitea.md](gitea.md)。

若 `ssh-keygen` 不存在：安装 Git for Windows 或 Windows OpenSSH 可选功能。

## GPG

需要本机 `gpg`（Gpg4win 或 Git 自带）。`ensure-gpg.ps1` 会按档案姓名/邮箱查找已有密钥；没有则 batch 生成 Ed25519，失败再回退 RSA 4096。生成密钥使用 `%no-protection`（无口令），便于 Cursor 非交互签名。若用户需要口令保护，应自行用 `gpg --full-generate-key` 创建，再把 key id 交给本流程。

列出密钥：

```powershell
gpg --list-secret-keys --keyid-format LONG
```

Git 配置（仅当前仓库）：

```powershell
git config user.signingkey KEY_ID
git config commit.gpgsign true
```

将公钥添加到 **Gitea → 设置 → SSH / GPG 密钥**。否则网页上可能不显示已验证，但本地签名仍然有效。详见 [gitea.md](gitea.md)。

## Token 与凭据

Token 只存在 `%USERPROFILE%\.git-skills\token.dpapi`，DPAPI 绑定当前 Windows 用户。换机器或换用户无法解密。

- 写入：用户本机运行 `store-token.ps1`（隐藏输入）
- 状态：`token-status.ps1` → `present` / `missing` / `invalid`
- 注入：`inject-credential.ps1 -RemoteUrl <url>` 通过 `git credential approve` 交给 Git Credential Manager，stdout 不含 Token

全局可设：

```powershell
git config --global credential.helper manager
```

HTTPS 远程：用户名为档案中的 `gitUsername`（Gitea 登录名），密码为访问令牌。非默认端口会写入 GCM（如 `host=git.example.com:3000`）。SSH 远程：推送走 SSH 密钥；脚本仍会为同一主机注入 HTTPS 凭据（不含 SSH 端口）。详见 [gitea.md](gitea.md)。

## 故障排查

| 现象 | 处理 |
| --- | --- |
| `profile=missing` | 用户本机运行 `store-profile.ps1` |
| `token=missing` / `invalid` | 用户本机运行 `store-token.ps1`（`invalid` 表示无法用当前用户 DPAPI 解密） |
| `git_username_missing` | 重新运行 `store-profile.ps1` 并填写 HTTPS 用户名 |
| `git_credential_approve_failed` | 确认已安装 Git for Windows / GCM，并设置 `credential.helper=manager` |
| `ssh_keygen_missing` | 安装 OpenSSH 或 Git for Windows |
| `ssh_agent=error` 或 `ssh_add=failed` | 以管理员启用 `ssh-agent` 服务，或用户手动 `ssh-add` |
| `Permission denied (publickey)` | 把 `public_key=` 贴到平台后再 `ssh -T` |
| `gpg_missing` | 安装 [Gpg4win](https://www.gpg4win.org/) 并重新打开终端 |
| `gpg_generate_failed` | 检查 gpg 是否可用；或用户交互生成后再跑 `ensure-gpg.ps1` |
| push 认证失败（HTTPS） | 确认 Token 对应该 host 且未过期；重新 `store-token` + `inject-credential` |
| 已有 `origin` | 不要改 remote；改为提交/推送或让用户决定 |
| `git log --show-signature` 无签名 | 确认 `commit.gpgsign=true` 且用了 `-S`；GPG 密钥存在 |
| `not_a_git_repo` | 先走初始化，或确认当前目录是仓库 |
| `remote_missing` | 用户提供 URL 后 `git remote add origin` |
| `secret_paths` | 从暂存区移除脚本列出的路径后再提交 |
| `ssh_key_missing`（日常推送） | 走初始化 SSH，或用户指定已有密钥路径 |
| `test-ssh` 失败 | 公钥是否已加到 Gitea；URL 端口是否正确；本机是否已接受 host key |
| HTTPS 自建端口失败 | 确认 URL 含 `:3000` 等端口；GCM 的 host 应为 `host:port` |
| 灰色开锁 / 找不到此签名对应的密钥 | 按官方：库中无可用密钥。完成 Gitea **验证**；对齐 `signingkey`；邮箱一致；见 [gitea.md](gitea.md) |
| GPG 验证签名不被接受 | 必须用 `echo "TOKEN"`（有换行）；用 `verify-gpg-challenge.ps1`，勿用 SSH 的 `echo -n` |
| SSH 验证签名不被接受 | 必须用 `echo -n`（无换行）；用 `verify-ssh-challenge.ps1` 或页面上的 PowerShell/`cmd` 提示 |

## 硬限制

- 不 force push
- 不修改已有 remote
- 不把 Token、私钥、`.dpapi` 写入仓库
- 不把 Token 放进命令行参数或对话
- 不修改全局 `user.name` / `user.email`