# gitlabtools

**Repository Path**: mydiguo/gitlabtools

## Basic Information

- **Project Name**: gitlabtools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitLab 工具集

> 从 GitLab 获取命名空间下仓库列表的 Python 工具集，支持批量克隆、项目关联分析等功能。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.6+-brightgreen.svg)](https://www.python.org/downloads/)
[![GitLab](https://img.shields.io/badge/GitLab-API-v4-orange.svg)](https://docs.gitlab.com/ee/api/)

## 目录

- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [工具列表](#工具列表)
- [项目架构](#项目架构)
- [使用示例](#使用示例)
- [配置说明](#配置说明)
- [常见问题](#常见问题)
- [更新日志](#更新日志)

## 功能特性

- 📋 **多格式输出** — 支持 simple、json、csv、clone-script 等多种输出格式
- 🔍 **Unity 项目检测** — 自动识别 Unity 项目（通过 Assets/ProjectSettings 目录）
- 🎯 **聚焦 Public 子模块** — 只处理包含 public 子模块的 Unity 项目
- 📦 **批量克隆** — 一键克隆 Unity 项目及其对应的 Android 仓库
- 🔄 **递归搜索** — 自动包含子群组的仓库
- 🔐 **多种认证** — 支持环境变量、配置文件多种认证方式
- 🌐 **多实例支持** — 支持 GitLab.com 和私有 GitLab 实例

## 快速开始

### 1. 安装依赖

```bash
# 使用安装脚本
python install.py

# 或手动安装
pip install requests python-gitlab
```

### 2. 获取访问令牌

1. 访问 GitLab
2. 进入 **User Settings** -> **Access Tokens**
3. 创建新的个人访问令牌
4. 选择权限：`api` 和 `read_repository`
5. 复制令牌（仅显示一次）

### 3. 设置环境变量

```bash
export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"
export GITLAB_URL="https://gitlab.com"  # 可选，默认 gitlab.com
```

### 4. 运行示例

```bash
# 列出仓库
python gitlab_list_repos.py mygroup

# 批量克隆
python gitlab_clone_all.py mygroup --ssh
```

## 工具列表

### gitlab_list_repos.py - 仓库列表工具

使用 `requests` 库调用 GitLab API 获取仓库列表。

**用法:**
```bash
# 简单列表（输出到 stdout）
python gitlab_list_repos.py mygroup

# JSON 格式（保存到 output/gitlab_repos_mygroup.json）
python gitlab_list_repos.py mygroup --format json

# CSV 格式（保存到 output/gitlab_repos_mygroup.csv）
python gitlab_list_repos.py mygroup --format csv

# 自定义 GitLab 实例
python gitlab_list_repos.py mygroup --url https://gitlab.example.com
```

**依赖:** `pip install requests`

### gitlab_clone_all.py - 批量克隆工具

克隆命名空间下所有仓库的工具。

**用法:**
```bash
# 克隆到当前目录
python gitlab_clone_all.py mygroup

# 克隆到指定目录
python gitlab_clone_all.py mygroup --output ~/projects

# 使用 SSH 协议
python gitlab_clone_all.py mygroup --ssh

# 仅克隆特定仓库
python gitlab_clone_all.py mygroup --filter "backend*"

# 跳过已存在的目录
python gitlab_clone_all.py mygroup --skip-existing

# 浅克隆（仅最近一次提交）
python gitlab_clone_all.py mygroup --depth 1
```

### find_unity_public_refs.py - Unity Public 子模块查找器

查找包含 public 子模块的 Unity 项目并记录其引用信息。

**用法:**
```bash
# 查找包含 public 子模块的 Unity 项目
python find_unity_public_refs.py

# 输出文件：
# - output/unity_public_refs.json (public 子模块引用信息)
# - output/unity_repos.json (所有 Unity 仓库列表)
```

### find_unity_android_repos.py - Unity Android 仓库查找器

查找包含 public 子模块的 Unity 项目及其对应的 Android 仓库。

**继承关系：** `UnityFinderBase → UnityPublicRefFinder → UnityAndroidFinder`

**用法:**
```bash
# 查找包含 public 的 Unity 项目和 Android 仓库
python find_unity_android_repos.py

# 同时生成 CSV（默认只生成 JSON）
python find_unity_android_repos.py --csv

# 输出文件：
# - output/unity_android_repos.json (Unity + Android 映射)
# - output/unity_repos.json (所有 Unity 仓库列表)
```

### gitlab_clone_unity.py - Unity 项目批量克隆器

从 JSON 文件读取并批量克隆 Unity 项目及其对应的 Android 仓库。

**继承关系：** `GitLabCloner → UnityCloner`

**用法:**
```bash
# 克隆所有 Unity 和 Android 仓库
python gitlab_clone_unity.py

# 只克隆 Unity 项目，不克隆 Android 仓库
python gitlab_clone_unity.py --no-android

# 克隆到指定目录
python gitlab_clone_unity.py --output ~/projects

# 使用 SSH 协议
python gitlab_clone_unity.py --ssh

# 跳过已存在的仓库
python gitlab_clone_unity.py --skip-existing

# 指定输入文件
python gitlab_clone_unity.py --input output/unity_android_repos.json

# 浅克隆
python gitlab_clone_unity.py --depth 1
```

### gitlab_tool.sh - 通用工具包装脚本
# 克隆所有 Unity 和 Android 仓库
python gitlab_clone_unity.py

# 只克隆 Unity 项目
python gitlab_clone_unity.py --no-android

# 克隆到指定目录
python gitlab_clone_unity.py --output ~/projects

# 跳过已存在的仓库
python gitlab_clone_unity.py --skip-existing
```

**功能:**
- 从 unity_android_repos.json 读取项目列表
- 克隆 Unity 项目及其对应的 Android 仓库
- 保持相同的目录结构

### gitlab_tool.sh - 通用工具包装脚本

Linux/Mac/Git Bash 通用脚本，整合所有功能。

**用法:**
```bash
# 测试连接
./gitlab_tool.sh test

# 列出所有命名空间
./gitlab_tool.sh list-all

# 克隆所有命名空间
./gitlab_tool.sh clone-all /path/to/output

# 清理输出目录
./gitlab_tool.sh clean-csv
```

## 项目架构

```
gitlabtools/
├── base/
│   ├── __init__.py
│   ├── gitlab_base.py          # GitLab API 基类
│   └── unity_finder_base.py    # Unity 项目查找器基类
├── output/                       # 输出目录
│   ├── gitlab_repos_*.json
│   ├── gitlab_repos_*.csv
│   ├── unity_public_refs.json   # Unity public 子模块引用
│   ├── unity_android_repos.json # Unity 项目及 Android 仓库映射
│   └── unity_repos.json         # Unity 仓库列表
├── gitlab_list_repos.py          # 仓库列表（继承 GitLabBase）
├── gitlab_clone_all.py           # 批量克隆（继承 GitLabBase）
├── gitlab_clone_unity.py         # Unity 项目克隆（继承 GitLabCloner）
├── find_unity_public_refs.py     # Unity public 子模块查找（继承 UnityFinderBase）
├── find_unity_android_repos.py   # Unity Android 仓库查找（继承 UnityPublicRefFinder）
├── gitlab_tool.sh                # Bash 包装脚本
├── install.py                    # 依赖安装脚本
├── README.md
├── QUICKSTART.md
├── EXAMPLES.md
└── CHANGELOG.md
```

### 核心类: GitLabBase

`base/gitlab_base.py` 提供通用 GitLab API 功能：

```python
from base.gitlab_base import GitLabBase

class MyTool(GitLabBase):
    def __init__(self, url, token):
        super().__init__(url, token)
        # 继承的方法:
        # - api_request()      # 通用 API 请求
        # - get_namespace()    # 获取命名空间
        # - get_projects_by_namespace()  # 获取项目列表
        # - is_unity_project() # 判断 Unity 项目
        # - get_repository_tree()  # 获取文件树
```

### 类继承关系

```
GitLabBase (base/gitlab_base.py)
├── GitLabRepoFetcher - 仓库列表获取
├── GitLabCloner - 批量克隆
│   └── UnityCloner - Unity + Android 克隆
└── UnityFinderBase (base/unity_finder_base.py) - 抽象基类
    └── UnityPublicRefFinder - Public 子模块查找
        └── UnityAndroidFinder - Android 仓库查找
```

### 抽象基类模式

`UnityFinderBase` 是抽象基类，子类需要实现三个方法：

1. `process_repo(repo, namespace, default_branch)` - 处理单个仓库
2. `get_result_filename()` - 返回输出文件名
3. `get_result_fields()` - 返回结果字段列表

基类自动提供：
- Unity 项目检测
- JSON 文件解析
- 结果保存（JSON 默认生成，CSV 可选）
- 统计信息打印

## 使用示例

### 场景 1: 查看命名空间下的所有仓库

```bash
# 简单列表
python gitlab_list_repos.py mycompany

# JSON 输出，保存到文件
python gitlab_list_repos.py mycompany --format json > repos.json
```

### 场景 2: 批量克隆所有仓库

```bash
# 克隆到当前目录
python gitlab_clone_all.py mycompany

# 克隆到指定目录
python gitlab_clone_all.py mycompany --output ~/projects

# 使用 SSH 协议 (需先配置 SSH 密钥)
python gitlab_clone_all.py mycompany --ssh

# 仅克隆包含 "backend" 的项目
python gitlab_clone_all.py mycompany --filter "backend"
```

### 场景 3: 查找并克隆包含 public 的 Unity 项目

完整工作流程：查找 → 生成 JSON → 克隆

```bash
# 1. 查找包含 public 子模块的 Unity 项目和对应的 Android 仓库
python find_unity_android_repos.py

# 输出文件：
# - output/unity_android_repos.json (Unity + Android 映射)
# - output/unity_repos.json (所有 Unity 仓库列表)

# 2. 克隆找到的项目
python gitlab_clone_unity.py --output ~/projects

# 或者只克隆 Unity 项目，不克隆 Android 仓库
python gitlab_clone_unity.py --no-android --output ~/projects

# 3. 查看统计信息
python find_unity_android_repos.py
# 统计信息会显示：
# - Unity 项目总数
# - 包含 public 子模块的项目数
# - 有对应 Android 仓库的项目数
```

### 场景 4: 导出项目列表到 CSV

```bash
python gitlab_list_repos.py mycompany --format csv > projects.csv
```

### 场景 4: 查找并克隆包含 public 的 Unity 项目

```bash
# 1. 查找包含 public 子模块的 Unity 项目和对应的 Android 仓库
python find_unity_android_repos.py

# 2. 克隆找到的项目
python gitlab_clone_unity.py --output ~/projects

# 或者只克隆 Unity 项目，不克隆 Android 仓库
python gitlab_clone_unity.py --no-android
```

## 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GITLAB_TOKEN` | GitLab 访问令牌 | 必填 |
| `GITLAB_URL` | GitLab 实例 URL | `https://gitlab.com` |

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GITLAB_TOKEN` | GitLab 访问令牌 | 必填 |
| `GITLAB_URL` | GitLab 实例 URL | `https://gitlab.com` |

### Bash 脚本配置 (gitlab_tool.sh)

编辑 `gitlab_tool.sh` 中的配置区域：

```bash
# 多命名空间配置 (空格分隔)
NAMESPACES="iaa/spidergame iaa/coloringgame iaa/solitairegame"
```

## 常见问题

### 问题: 获取命名空间失败

**原因**: 令牌权限不足或命名空间路径错误

**解决**:
1. 确认令牌有 `read_api` 权限
2. 使用完整路径（如 `mygroup/subgroup` 而非 `subgroup`）
3. 在 GitLab 网页确认命名空间存在

### 问题: 401 Unauthorized

**原因**: 令牌无效或过期

**解决**:
1. 生成新的访问令牌
2. 更新环境变量或配置文件

### 问题: SSH 克隆失败

**原因**: SSH 密钥未配置

**解决**:
1. 生成 SSH 密钥: `ssh-keygen -t ed25519`
2. 在 GitLab 添加公钥: User Settings → SSH Keys
3. 测试连接: `ssh -T git@gitlab.com`

### 问题: JSON 文件解析失败

**原因**: 输出污染（进度信息混入 JSON）

**解决**: 使用 `--format` 参数明确指定格式，或过滤 stderr

## 更新日志

查看 [CHANGELOG.md](CHANGELOG.md) 了解详细版本历史。

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 相关链接

- [GitLab API 文档](https://docs.gitlab.com/ee/api/)
- [快速开始指南](QUICKSTART.md)
- [使用示例](EXAMPLES.md)
- [更新日志](CHANGELOG.md)