# 完整 Git 工作流

Agent 在 SKILL.md 路由到这些路径后再读本文件。Windows PowerShell。默认远程为 **Gitea**（见 [gitea.md](gitea.md)）。认证一律走 `prepare-auth.ps1` / `prepare-push.ps1`，不得在对话中索取 Token。

先探测：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/repo-status.ps1"
```

## Clone

用户提供 **Gitea** URL（以及可选目录名）。不必已在仓库内。

示例：`https://git.example.com:3000/owner/repo.git` 或 `ssh://git@git.example.com:2222/owner/repo.git`。

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/profile-status.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/prepare-auth.ps1" -RemoteUrl "<url>"
git clone "<url>" "<optional-dir>"
```

进入克隆目录后跑 `prepare-commit.ps1`（只写 local 作者与签名，不提交）。

SSH 且 `ssh_key_missing`：停下来，让用户先走 Init 的 SSH，或改用 HTTPS URL。

Init 后若需验证 SSH：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/test-ssh.ps1" -RemoteUrl "<url>"
```

不要把 URL 里的密码打印到对话。不要 `git clone --recursive` 除非用户要求。不要把示例默认写成 github.com。

## Fetch / Pull

已有仓库。不要在 pull 前擅自 commit。

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/prepare-push.ps1"
git fetch origin
```

- 只要拉取远程引用：到此为止
- 用户要更新当前分支：`git pull --ff-only origin`（当前分支已有上游则 `git pull --ff-only`）
- `--ff-only` 失败：报告 diverged，询问 merge 还是由用户决定；不要擅自 rebase，不要 `--force`

脏工作区时先报告 `dirty=yes`，问是否先 stash，不要覆盖未提交改动。

## Branch

```powershell
git branch -vv
git status -sb
```

- 列出：上面即可
- 切换：`git switch <name>`（没有则不要乱建）。未提交改动冲突时停下
- 新建并切换：`git switch -c <name>`（用户给了分支名）
- 删除本地分支：仅当用户明确要求，且不是当前分支：`git branch -d <name>`。拒绝 `-D` 除非用户明确要强制删除
- 不要 `push --delete` 远程分支，除非用户明确要求删除远程分支

## Merge

仅当用户要求合并。

```powershell
git status -sb
git switch <target>
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/prepare-push.ps1"
git fetch origin
git merge --no-ff <source>
```

冲突：停下，列出冲突文件，不要 `--abort` 除非用户要求放弃。合并提交信息仍用中文 `类型: 描述`（多为 `合并: 将 xx 合入 yy`），需要签名则 `git commit -S`。

不要 `rebase -i`。用户明确要求 rebase 时用非交互 `git rebase <onto>`；冲突同样停下。

## Tag

```powershell
git tag -l
```

签名标签（与提交签名同一把 GPG 钥）：

```powershell
git tag -s "<tag>" -m @"
类型: 描述
"@
```

推送标签仅当用户要求：`prepare-push.ps1` 然后 `git push origin "<tag>"`。不要 `git push --tags` 除非用户要推送全部标签。

## Stash

- 暂存：`git stash push -u -m "<中文说明>"`（用户要求保存未提交改动时）
- 列出：`git stash list`
- 恢复：`git stash pop` 仅当用户要求；冲突则停下
- 不要 `stash drop` / `stash clear` 除非明确要求

## Inspect（只读）

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "<scripts>/repo-status.ps1"
git status
git diff
git diff --staged
git log --show-signature -8
git remote -v
```

不要因此提交或推送。不要 `git config --list` 里把 credential 明文贴进对话。

## 安全撤销

允许（用户要求撤销暂存/改动时）：

```powershell
git restore --staged -- <paths>
git restore -- <paths>
```

禁止除非用户写明要丢弃历史/覆盖远程：

- `git reset --hard`
- `git checkout --` 覆盖全部
- `git push --force` / `--force-with-lease`
- `git rebase -i`、`git filter-branch`、`git push --delete`

`git reset --soft HEAD~1` 仅当：用户明确要求、HEAD 是当前用户刚做的提交、且尚未推送。