129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# Git 与 Gitea 规范
|
||
|
||
## 1. 当前策略
|
||
|
||
本项目使用本地 Git 和用户自建 Gitea，不使用 GitHub，也不创建 GitHub Actions。
|
||
|
||
| 配置项 | 值 |
|
||
|---|---|
|
||
| Gitea 基础地址 | `https://git.foximao.com/` |
|
||
| 项目账号 | `FoXiMao` |
|
||
| 唯一远程仓库 | `https://git.foximao.com/FoXiMao/a-share-analysis.git` |
|
||
| 远程名 | `origin` |
|
||
| 配置作用域 | 当前项目 `.git/config` |
|
||
|
||
密码不属于项目文档。它不得出现在仓库文件、Git 历史、远程 URL、脚本或命令参数中；首次认证时由 Git 凭据助手请求，并交由 macOS Keychain 保存。
|
||
|
||
## 2. 分支与提交
|
||
|
||
- `main` 始终保持可验证和可回退。
|
||
- 普通功能使用 `feature/<功能编号>-<短名称>`。
|
||
- 修复使用 `fix/<功能编号>-<短名称>`。
|
||
- 提交必须符合中文 Conventional Commit，仓库通过 `.githooks/commit-msg`检查。
|
||
- 禁止强推共享 `main`，禁止使用破坏历史的回退方式处理已共享版本。
|
||
|
||
首次克隆后执行：
|
||
|
||
```bash
|
||
git config core.hooksPath .githooks
|
||
```
|
||
|
||
## 3. Gitea 项目级接入
|
||
|
||
在本项目根目录执行以下项目级配置：
|
||
|
||
```bash
|
||
git remote add origin https://git.foximao.com/FoXiMao/a-share-analysis.git
|
||
git config --local credential.helper osxkeychain
|
||
git config --local credential.useHttpPath true
|
||
git config --local credential.username FoXiMao
|
||
git config --local remote.pushDefault origin
|
||
```
|
||
|
||
`credential.useHttpPath=true` 让同一 Gitea 域名下不同仓库按路径区分凭据；所有设置使用 `--local`，只写入本项目不可提交的 `.git/config`。禁止使用 `git config --global` 配置本项目账号、凭据助手或默认推送目标。
|
||
|
||
只读连通性检查：
|
||
|
||
```bash
|
||
GIT_TERMINAL_PROMPT=0 git ls-remote origin
|
||
```
|
||
|
||
首次需要写权限时，在交互式终端推送并输入凭据：
|
||
|
||
```bash
|
||
git push -u origin main
|
||
```
|
||
|
||
首次认证完成后，凭据由 macOS Keychain 管理。GOV-004 起，用户已授予本项目持续推送权限，验证通过的提交必须立即推送。建议在 Gitea 中保护 `main`：禁止强推、要求状态检查通过、要求变更说明关联功能编号。
|
||
|
||
## 4. 提交后强制推送
|
||
|
||
普通提交只推送当前分支：
|
||
|
||
```bash
|
||
git push origin "$(git branch --show-current)"
|
||
```
|
||
|
||
本次创建版本标签时，在分支推送成功后精确推送该标签：
|
||
|
||
```bash
|
||
git push origin <本次标签名>
|
||
```
|
||
|
||
不得使用 `git push --tags` 替代精确标签推送，避免发布其他未确认标签。不得使用 `--force` 或 `--force-with-lease`。
|
||
|
||
分支推送后核对远程 SHA：
|
||
|
||
```bash
|
||
current_branch="$(git branch --show-current)"
|
||
git rev-parse "$current_branch"
|
||
git ls-remote origin "refs/heads/$current_branch"
|
||
```
|
||
|
||
两条结果必须指向相同提交。带注释标签核对时，应比较标签最终指向的提交，而不是标签对象本身。
|
||
|
||
如果认证、网络、分支保护或非快进检查导致推送失败：
|
||
|
||
1. 保留本地提交和标签，不删除、不 amend、不重写历史。
|
||
2. 记录失败命令、时间和不包含凭据的错误摘要，将任务标记为未完成。
|
||
3. 先获取并审查远程差异；禁止自动 merge、rebase、强推或覆盖未知提交。
|
||
4. 解决原因后重试同一个精确推送命令，并重新核对远程引用。
|
||
|
||
提交 SHA、远程分支、推送结果和本次标签结果必须写入对应功能档案。
|
||
|
||
## 5. 配置检查与移除
|
||
|
||
检查当前项目和全局配置的边界：
|
||
|
||
```bash
|
||
git remote -v
|
||
git config --local --get credential.helper
|
||
git config --local --get credential.useHttpPath
|
||
git config --global --get-all credential.helper
|
||
git config --global --get remote.pushDefault
|
||
```
|
||
|
||
如需解除本项目 Gitea 接入，执行：
|
||
|
||
```bash
|
||
git remote remove origin
|
||
git config --local --unset credential.helper
|
||
git config --local --unset credential.useHttpPath
|
||
git config --local --unset credential.username
|
||
git config --local --unset remote.pushDefault
|
||
```
|
||
|
||
上述操作只影响本项目。Keychain 中已保存的凭据需要在“钥匙串访问”中按 `git.foximao.com` 单独删除。
|
||
|
||
## 6. 版本与标签
|
||
|
||
发布使用带注释标签，例如：
|
||
|
||
```bash
|
||
git tag -a v0.1.0 -m "发布市场综合概览 v0.1.0"
|
||
```
|
||
|
||
标签必须指向通过验证的提交。应用回退优先选择既有标签和不可变构建产物，而不是重新拼装旧版本。
|
||
|
||
本规范的强制推送规则由 GOV-004 建立，并取代 GOV-003 中“只接入、不主动推送”的历史规则；GOV-003 原文保留用于审计当时决策。
|