# repo_sync

**Repository Path**: self_5/repo_sync

## Basic Information

- **Project Name**: repo_sync
- **Description**: 一个用于批量同步本地目录到gitee仓库的脚本
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-11
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gitee仓库同步工具

自动将本地Git仓库同步到Gitee的Python工具。支持批量处理、自动创建仓库、智能提交未保存的变更。

## ✨ 功能特性

- 🚀 **批量同步**: 支持一次性同步多个本地仓库
- 🔄 **智能检测**: 自动检测本地仓库是否已关联Gitee
- 📦 **自动创建**: 如果Gitee仓库不存在，自动通过API创建
- 🗑️ **关联解除**: 支持一键移除本地仓库的Gitee远程关联，便于重新配置
- 💾 **自动提交**: 检测未提交的变更并自动提交
- 🔐 **安全认证**: 使用Gitee Personal Access Token进行安全认证
- 🎨 **美观输出**: 使用Rich库提供彩色、格式化的终端输出
- 🧪 **空运行模式**: 支持dry-run模式，安全测试而不实际执行操作
- ⚙️ **灵活配置**: 通过YAML文件和环境变量灵活配置

## 📋 前置要求

### 环境要求

- **Python**: 3.8 或更高版本
- **Git**: 已安装并配置
- **UV**: Python包管理器（推荐）
- **Gitee账户**: 需要有效的Gitee账户和Personal Access Token

### 获取Gitee Personal Access Token

1. 登录Gitee账户
2. 访问 https://gitee.com/profile/personal_access_tokens
3. 点击"生成新令牌"
4. 设置令牌描述，选择权限：
   - ✅ **projects** (必需 - 用于创建和管理仓库)
5. 生成并保存令牌（只显示一次，请妥善保管）

## 🚀 快速开始

### 1. 安装UV（如果未安装）

```powershell
# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. 克隆或下载本项目

```powershell
cd e:\projects\self\repo_sync
```

### 3. 安装依赖

使用UV安装项目依赖：

```powershell
uv sync
```

或使用pip：

```powershell
pip install -r requirements.txt
```

### 4. 配置环境变量

复制环境变量模板并填入您的信息：

```powershell
copy .env.example .env
```

编辑 `.env` 文件：

```env
GITEE_ACCESS_TOKEN=你的gitee访问令牌
GITEE_USERNAME=你的gitee用户名
GITEE_ORGANIZATION=        # 可选：组织名称（留空则创建个人仓库）
```

> [!NOTE]
> **组织仓库支持**：
> - 如果设置了 `GITEE_ORGANIZATION`，新仓库将创建在该组织下
> - 留空则创建在个人账户下
> - 已存在的仓库（无论在组织还是个人账户）都会正常同步

### 5. （可选）配置同步选项

编辑 `config.yaml` 文件以自定义同步行为：

```yaml
repository:
  private: true  # 创建私有仓库
  default_description: "自动同步的仓库"
  name_suffix: ""  # 仓库名称后缀（如 "-backend", "-web"）

git:
  commit_message: "backup:备份代码"  # 自动提交消息
  remote_name: "origin"  # 远程仓库名称
```

> [!TIP]
> **仓库名称后缀**: 使用 `name_suffix` 可以为所有仓库添加统一后缀。例如：
> - 设置 `name_suffix: "-backend"` 会将目录 `my_project` 创建为 `my_project-backend`
> - 设置 `name_suffix: "-web"` 会将目录 `admin_panel` 创建为 `admin_panel-web`
> - 留空则使用原始目录名称



## 📖 使用方法

### 方式1: 同步指定目录

```powershell
# 使用UV运行
uv run python sync_to_gitee.py E:\projects\repo1 E:\projects\repo2

# 或直接运行
python sync_to_gitee.py E:\projects\repo1 E:\projects\repo2
```

### 方式2: 从文件读取目录列表

1. 编辑 `directories.txt` 文件，每行一个目录路径：

```text
E:\projects\repo1
E:\projects\repo2
E:\work\important_repo
```

2. 运行同步：

```powershell
uv run python sync_to_gitee.py --from-file directories.txt
```

### 方式3: 结合 init_git_repos.py 批量初始化并同步

```powershell
# 步骤1: 初始化所有子目录的Git仓库
uv run python init_git_repos.py E:\projects

# 步骤2: 将输出的仓库路径保存到文件
# （手动复制或使用脚本）

# 步骤3: 批量同步到Gitee
uv run python sync_to_gitee.py --from-file directories.txt
```

### 方式4: 批量移除Gitee关联

在某些情况下（如远程仓库URL变化、或是同步失败需要重置），您可以使用新增的 `remove_gitee_remote.py` 脚本：

```powershell
# 1. 安全预览哪些仓库将被解除关联（不会实际修改）
uv run python remove_gitee_remote.py --from-file directories.txt --dry-run

# 2. 实际执行批量解除
uv run python remove_gitee_remote.py --from-file directories.txt

# 3. 指定单个目录解除
uv run python remove_gitee_remote.py E:\projects\repo1
```


### 空运行模式（推荐首次使用）

在首次使用时，建议先使用空运行模式测试：

```powershell
uv run python sync_to_gitee.py --dry-run E:\projects\repo1
```

这会显示将要执行的操作，但不会实际修改仓库或调用API。

## 🔄 工作流程

脚本会按以下步骤处理每个仓库：

```mermaid
graph TD
    A[开始] --> B{是Git仓库?}
    B -->|否| C[跳过 - 不是Git仓库]
    B -->|是| D{有提交记录?}
    D -->|否| E[跳过 - 无提交]
    D -->|是| F{已关联Gitee?}
    F -->|是| K[使用现有远程]
    F -->|否| G{Gitee仓库存在?}
    G -->|是| H[获取仓库URL]
    G -->|否| I[创建Gitee仓库]
    H --> J[关联远程仓库]
    I --> J
    J --> K
    K --> L{有未提交变更?}
    L -->|是| M[自动提交变更]
    L -->|否| N[推送到Gitee]
    M --> N
    N --> O[完成]
    C --> P[结束]
    E --> P
    O --> P
```

## 📝 命令行参数

```
usage: sync_to_gitee.py [-h] [-f FILE] [-c FILE] [--dry-run] [--env-file FILE]
                        [directories ...]

positional arguments:
  directories           要同步的仓库目录路径

optional arguments:
  -h, --help            显示帮助信息
  -f FILE, --from-file FILE
                        从文件读取目录列表（每行一个路径）
  -c FILE, --config FILE
                        配置文件路径 (默认: config.yaml)
  --dry-run             空运行模式，不实际执行操作
  --env-file FILE       环境变量文件路径 (默认: .env)
```

## 🎯 使用场景

### 场景1: 备份所有项目到Gitee

```powershell
# 1. 使用 init_git_repos.py 确保所有项目都是Git仓库
uv run python init_git_repos.py E:\projects

# 2. 创建目录列表文件
# 将 init_git_repos.py 的输出保存到 directories.txt

# 3. 批量同步
uv run python sync_to_gitee.py --from-file directories.txt
```

### 场景2: 定期同步特定项目

```powershell
# 创建专用的目录列表
echo E:\work\project1 > work_repos.txt
echo E:\work\project2 >> work_repos.txt

# 定期运行同步
uv run python sync_to_gitee.py --from-file work_repos.txt
```

### 场景3: 迁移单个仓库

```powershell
# 直接指定单个仓库
uv run python sync_to_gitee.py E:\projects\my_important_project
```

## ⚠️ 注意事项

### API速率限制

Gitee API有速率限制：
- **未认证请求**: 60次/小时
- **认证请求**: 5000次/小时

本工具使用认证请求，通常不会触及限制。如果遇到速率限制，脚本会自动重试。

### SSH密钥配置

确保您已配置SSH密钥：

```powershell
# 生成SSH密钥（如果没有）
ssh-keygen -t ed25519 -C "your_email@example.com"

# 查看公钥
type ~\.ssh\id_ed25519.pub
```

将公钥添加到Gitee：https://gitee.com/profile/sshkeys

### 仓库可见性

默认创建**私有仓库**。要创建公共仓库，修改 `config.yaml`：

```yaml
repository:
  private: false
```

### 分支名称

脚本会自动检测当前分支并推送。如果本地使用 `main` 分支而不是 `master`，不需要额外配置。

### 组织仓库配置

支持在Gitee组织下创建仓库：

**创建组织仓库**：

```env
# .env 文件
GITEE_ORGANIZATION=your_organization_name
```

**创建个人仓库**：

```env
# .env 文件
GITEE_ORGANIZATION=
# 或者完全不设置这个变量
```

**注意事项**：

- 确保你有该组织的仓库创建权限
- 已存在的仓库无论在组织还是个人账户下都能正常同步
- 新创建的仓库会根据 `GITEE_ORGANIZATION` 设置决定归属

## 🐛 故障排除

### 问题1: Token验证失败

**错误**: `Token验证失败: 401 Unauthorized`

**解决方案**:
1. 检查 `.env` 文件中的 `GITEE_ACCESS_TOKEN` 是否正确
2. 确认token未过期
3. 检查token权限是否包含 `projects`

### 问题2: 推送失败 - SSH密钥

**错误**: `Permission denied (publickey)`

**解决方案**:
1. 确认已添加SSH公钥到Gitee账户
2. 测试SSH连接：`ssh -T git@gitee.com`
3. 检查SSH代理是否运行

### 问题3: 仓库已存在但无法访问

**错误**: `API错误 (403): Forbidden`

**解决方案**:
1. 检查仓库是否属于您的账户
2. 如果仓库在组织下，确保有足够权限
3. 检查 `GITEE_USERNAME` 是否正确

### 问题4: 未提交的变更提交失败

**错误**: `提交失败: nothing to commit`

**解决方案**:
1. 检查是否有 `.gitignore` 忽略了所有变更
2. 确认文件确实有修改
3. 检查Git配置是否正确

## 📦 项目结构

```
repo_sync/
├── sync_to_gitee.py      # 主同步脚本
├── remove_gitee_remote.py# 移除Gitee远程关联脚本
├── gitee_api.py          # Gitee API客户端封装
├── git_operations.py     # Git操作辅助函数
├── init_git_repos.py     # Git仓库初始化脚本
├── config.yaml           # 配置文件
├── .env.example          # 环境变量模板
├── .env                  # 环境变量（需自行创建）
├── directories.txt       # 目录列表示例
├── pyproject.toml        # UV项目配置
├── .gitignore           # Git忽略规则
└── README.md            # 本文档
```

## 🔧 依赖说明

- **requests**: HTTP请求库，用于调用Gitee API
- **PyYAML**: YAML解析库，用于读取配置文件
- **python-dotenv**: 环境变量管理
- **rich**: 终端美化输出

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📞 支持

如有问题，请提交Issue或查看Gitee API文档：
- Gitee API文档: https://gitee.com/api/v5/swagger
- Gitee帮助中心: https://gitee.com/help

## 🎉 致谢

感谢Gitee提供优秀的代码托管平台和开放API！