# gitee-github-mirror

**Repository Path**: htzsl/gitee-github-mirror

## Basic Information

- **Project Name**: gitee-github-mirror
- **Description**: Sync-GiteeToGitHub.ps1 将一个公开可读取的 Gitee HTTPS 仓库克隆为本地 bare mirror，并镜像推送到当前 gh 登录用户下同名的 GitHub 仓库。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gitee 到 GitHub 镜像工具

`Sync-GiteeToGitHub.ps1` 将一个公开可读取的 Gitee HTTPS 仓库克隆为本地 bare mirror，并镜像推送到当前 `gh` 登录用户下**同名**的 GitHub 仓库。

## 前置条件

- PowerShell 7+
- Git 2.33+（支持 `git push --atomic`）
- GitHub CLI 2.94+，已通过 `gh auth login` 登录
- Gitee 源仓库必须能被本机 Git 读取。

脚本用 `gh api user` 获取目标账户，不读取或显示 GitHub 令牌，不调用 `gh auth token`，也不会修改全局 Git 配置。目标 URL 固定构造成无用户信息的 `https://github.com/<login>/<repo>.git`。

## 使用方法

先检查 URL、克隆和本地对象完整性。若目标已存在，DryRun 还会发送安全的 Git push dry-run；若目标不存在，DryRun 不创建仓库，也不会探测推送：

```powershell
pwsh .\Sync-GiteeToGitHub.ps1 https://gitee.com/acme/widgets.git -DryRun
```

真实镜像必须显式确认目标名。非交互自动化必须传入正确的 `-ConfirmMirror`：

```powershell
pwsh .\Sync-GiteeToGitHub.ps1 https://gitee.com/acme/widgets -Visibility private -NonInteractive -ConfirmMirror your-github-login/widgets
```

交互式调用可省略 `-ConfirmMirror`，脚本会要求输入完整的 `owner/repo`。新仓库默认是 private。即使指定 `-Visibility public`，脚本也会先创建 private 仓库，只有镜像推送与逐 refs 后验都成功后才将其改为 public；已存在仓库的可见性不会修改。`-KeepWorkdir` 仅用于故障排查，默认会清理临时 bare mirror。

## 安全边界与限制

- 只接受 `https://gitee.com/<owner>/<repo>[.git]`，拒绝 HTTP、非 Gitee 域名、端口、用户信息、query 和 fragment。路径段会在百分号解码后重新做严格字符检查；能解码为 `/`、`?`、`#`、`@`、`:`、空白或控制字符的输入都会被拒绝。
- 不传确认绝不创建仓库或真实推送。DryRun 不创建、也不真实推送。
- 已有目标会先经 GitHub API 检查是否 archived 以及当前账户是否有 push 权限。
- 真实推送前先运行 `git push --mirror --atomic --dry-run --porcelain`；真实操作使用 `git push --mirror --atomic --porcelain`。
- 新建目标必须在远端 preflight 前存在，因此 clone 和 `fsck` 成功、且用户确认后会创建一个 private 空仓库。如果随后 preflight、真实推送、refs 后验或公开可见性更新失败，该新仓库会保持 private，脚本会输出醒目警告和仓库 URL；需要时请手动检查或删除它。
- `--mirror` 会使目标 refs 与源完全一致，可能删除目标独有分支、标签、notes 和其他 refs。受保护分支、规则集、Git LFS、GitHub Actions、议题、PR、release、Wiki 和仓库设置不会被迁移，也可能使推送失败。
- 推送完成后脚本逐项比较本地和远端 refs。网络读失败时会重试一次只读核验；仍失败则以“验证不确定”失败退出。
- `git` 与 `gh` 必须通过 `Get-Command` 解析为 `Application`，并使用其绝对可执行路径调用；不会接受同名 alias、function 或 cmdlet。

## 测试

测试依赖 Pester 3.4 兼容语法，并只验证纯函数和 Mock 行为：

```powershell
Invoke-Pester .\tests\Sync-GiteeToGitHub.Tests.ps1
```

远程 GitHub/Gitee 流程未在测试中执行。运行真实镜像前，请先以 `-DryRun` 检查。