# Git Workflow

> Git 工作流与版本管理技能，规范分支策略、提交信息和发布流程。 触发场景： - 用户需要创建分支或合并代码 - 用户需要规范提交信息格式 - 用户需要管理版本发布流程 触发词：Git、分支、提交、合并、版本发布

- Skill: `bkywksj/git-workflow-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bkywksj/git-workflow-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bkywksj/git-workflow-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: bkywksj (https://skillmd.com/u/bkywksj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bkywksj/git-workflow-2

---


# Git 工作流与版本管理

## 概述

Tauri Desktop App 的 Git 工作流与版本管理技能，规范分支命名、提交信息格式和发布流程。

---

## 🔴 多远端架构（knowledge_base 项目）

本项目有五个远端（`git remote -v`）：

| remote | 角色 | 定位 |
|--------|------|------|
| **`origin`** | **Gitee (`gitee.com/bkywksj/knowledge-base`)** | 国内主仓 |
| **`github`** | **GitHub (`github.com/bkywksj/knowledge-base`)** | 主 CI 构建源 + 海外开源镜像（账号 bkywksj） |
| **`github2`** | **GitHub (`git@github.com:allebamala/knowledge-base.git`，SSH)** | 备用 CI（`bkywksj` 的 Actions 配额耗尽时切到这里跑）— 私有仓库；用 `~/.gh_token_allebamala`；本机 SSH key 已绑 allebamala |
| **`github3`** | **GitHub (`https://github.com/elginbolds-cell/knowledge-base.git`，token URL)** | 备用 CI（`bkywksj` + `allebamala` 都耗尽时切到这里）— 私有仓库；用 `~/.gh_token_elginbolds`；**远端 URL 必须内嵌 token**（不要存进 git credential helper —— 会覆盖 github.com 默认凭证 bkywksj） |
| `upstream` | 原 tauri 框架模板 | 极少用，仅在同步模板时拉取 |

> **Actions Secrets 同步状态**：
> - `github` (bkywksj)：✅ 已配齐（TAURI_SIGNING_PRIVATE_KEY + ANDROID_*）
> - `github2` (allebamala)：✅ 已配齐（与 github 一致）
> - `github3` (elginbolds-cell)：⚠️ **首次切换前需在 Settings → Secrets and variables → Actions 手动配置**：`TAURI_SIGNING_PRIVATE_KEY`、`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`（空字符串）、`ANDROID_KEYSTORE_BASE64`、`ANDROID_KEYSTORE_PASSWORD`、`ANDROID_KEY_ALIAS`、`ANDROID_KEY_PASSWORD`。配齐前 CI 会失败。

### 历史已对齐（v1.3.0 起）

v1.3.0 发布时（2026-04-26）已经把 GitHub 历史 force-sync 到 Gitee，**两端 commit hash 完全一致、共享 git 祖先**，从此可以走标准 git workflow，**不再需要 cherry-pick 同步**。

> 备份分支 `backup-before-gh-sync-v1.3.0` 还留在 Gitee 上，万一以后发现丢了什么内容可以从这里救回来。

---

## 🔴 提交推送规则（knowledge_base 项目）

### 「日常 commit」— 用户说"提交推送"时

**默认推 origin + github**（两端历史已统一，没有任何冲突风险）；`github2` / `github3` 是备用镜像，平时可不推，需要切备用 CI / 发版前再同步一次：

```bash
git push origin master       # Gitee 主仓
git push github master       # GitHub 主（CI 触发源 + 海外镜像）
# git push github2 master    # GitHub 备用 1（按需，bkywksj 配额耗尽切过去前同步）
# git push github3 master    # GitHub 备用 2（按需，bkywksj + allebamala 都耗尽时同步）
```

如果用户只说"推 Gitee"，按字面只推 origin。

### 「发布版本」— 调 /release 时

走下方"发布流程"章节；tag 推到**当前使用的 CI 远端**（`github` / `github2` / `github3` 之一，发布前必须询问用户选哪个）。Tag 只推到一个仓库 = 只触发一个 CI，避免重复构建浪费配额。

### ⛔ 注意事项

1. **不要在 master 上直接 force push**（除非你像 v1.3.0 那种明确做"两端历史合并"，且已备份）
2. 推送前 fetch 各端确认本地是最新的，避免覆盖另一端有但本地没有的 commit

---

## 分支策略

### 分支命名规范

| 分支类型 | 命名格式 | 示例 |
|---------|---------|------|
| 主分支 | `master` / `main` | `master` |
| 开发分支 | `dev` | `dev` |
| 功能分支 | `feature/{功能名}` | `feature/file-manager` |
| 修复分支 | `fix/{问题描述}` | `fix/window-resize-crash` |
| 发布分支 | `release/v{版本}` | `release/v0.2.0` |

---

## 提交信息规范

### Conventional Commits

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

### Type 定义

| Type | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(rust): 添加文件读写 Command` |
| `fix` | 修复 Bug | `fix(react): 修复状态更新不生效` |
| `refactor` | 重构 | `refactor(rust): 重构错误处理为 thiserror` |
| `docs` | 文档 | `docs: 更新 README` |
| `style` | 格式 | `style(rust): cargo fmt 格式化` |
| `test` | 测试 | `test(rust): 添加 Command 单元测试` |
| `chore` | 杂务 | `chore: 更新 Cargo.toml 依赖` |
| `build` | 构建 | `build: 配置 Tauri 打包参数` |

### Scope 建议

| Scope | 说明 |
|-------|------|
| `rust` | Rust 后端代码 |
| `react` | React 前端代码 |
| `tauri` | Tauri 配置 (tauri.conf.json) |
| `caps` | Capabilities 权限配置 |
| `deps` | 依赖更新 |

### 多行提交信息

首选：Write 一个 UTF-8 无 BOM 文件 → `git commit -F <文件>`（用后删，shell 无关、中文不乱码）。
🔴 `@'...'@` 是 PowerShell here-string，只能在 PowerShell 工具用；放进 Bash 会在 message 头尾各粘一行 `@`。

---

## 发布流程（CI 全自动模式）

> 项目已配置 GitHub Actions CI，**本地不需要执行 `pnpm tauri build`**。
> 使用 `/release` 命令可自动完成全部发布流程。

```
1. 更新版本号（三处同步）
   - package.json: version
   - src-tauri/Cargo.toml: version
   - src-tauri/tauri.conf.json: version
2. 更新 release 仓库 README.md（下载链接 + 版本历史）
3. 提交并推送 release 仓库 README 变更
4. 提交源码仓库 + 推送到 GitHub
5. 打 Git Tag（v*.*.* 格式）并推送
   → 自动触发 GitHub Actions CI
   → CI 构建 Windows/macOS/Linux 三平台安装包
   → CI 自动推送产物 + update.json 到 release 仓库
```

### 快速发布

```bash
# 使用 /release 命令一键发布
/release
```

### 手动发布（备用）

```bash
# 1. 更新版本号后提交
git add src-tauri/tauri.conf.json src-tauri/Cargo.toml package.json
git commit -m "release: vX.Y.Z"

# 2. 推送到 GitHub
git push <github_remote> <主分支>

# 3. 打 Tag 触发 CI
git tag vX.Y.Z
git push <github_remote> vX.Y.Z
```

---

## 🔴 远程 Git 操作优先用 Sigil（检测到才启用，没装则无感回退）

> 需要远程认证的 git 操作（`push` / `clone` / 推送后远端核对），**本会话检测到 Sigil 就优先走它**（凭据由保险库注入，明文不外泄、不落 `.git/config`）；**Sigil 没装就照常 `git push`，流程不受影响**。

### 🔴 三条铁律

1. **零明文**：任何平台的 git 推送 / 建仓 / API 一律走 Sigil，**永不**手拼 `https://user:TOKEN@host` 或明文传 token（明文会随 `.git/config` 同步到云盘泄露）。
2. **username 别用默认**：`git_push` 推 **Gitee / GitCode** 时 `username` 必传该平台真实登录账号，用默认 `x-access-token` 会认证失败；GitHub 可用默认 `x-access-token`。
3. **失败即停**：Sigil 报错（锁库 / 缺凭据 / 能力未启用）→ 停下提示用户处理，**绝不**回退明文 token。

### 用法

- **检测**：本会话能 `ToolSearch` 到 `mcp__sigil__git_push` → 可用；查不到 → 回退普通 `git push`，不报错不卡流程。
- **选凭据**：先 `mcp__sigil__list_credentials` 按平台（`gitee_token` / `gitcode_token` / `github_token`）查到对应 `credential_name`，**不写死猜**。
- **推送**：`mcp__sigil__git_push(repo_path=<仓库绝对路径>, remote=<远程名>, branch=<分支>, credential_name=<查到的>, username=<Gitee/GitCode 传真实账号 · GitHub 用 x-access-token>)`。多 remote 逐个推。
- **建仓 / 改描述 / 查提交**：`mcp__sigil__{平台}_repo_create`（🔴 `private: true`，绝不建公开仓）/ `mcp__sigil__{平台}_repo_update` / `mcp__sigil__{平台}_commits_list`。
- **失败**：按 Sigil 错误前缀处置（解锁金库 / 补凭据 / 启用能力），绝不落明文 token。

## 常见错误

| 错误做法 | 正确做法 |
|---------|---------|
| 直接在 master 上开发 | 创建功能分支开发 |
| 提交信息写"修改代码" | 按 Conventional Commits 规范编写 |
| 版本号只改 package.json | 同步修改 Cargo.toml 和 tauri.conf.json |
| 提交 target/ 编译产物 | 确保 .gitignore 正确配置 |