# gitlab-clone-tool

**Repository Path**: xuritiankong/gitlab-clone-tool

## Basic Information

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

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitLab 批量克隆工具 (GitLab Clone Tool)

#### 介绍
GitLab 批量克隆工具是一个基于 Python 和 tkinter 构建的 Windows GUI 桌面应用程序。该工具主要用于从 GitLab 批量获取并克隆指定群组（Group）及其所有子群组（Subgroups）下的项目。通过图形化界面操作，免去繁琐的命令行交互，支持可视化选择项目以及并发克隆，极大提升开发者在多项目环境下的代码同步效率。

#### 主要特性
*   **开箱即用**：提供图形用户界面 (GUI)，无需在终端手动执行复杂的脚本。
*   **层级树状展示**：自动拉取并解析指定 GitLab 群组下的所有子组和项目，以树形结构呈现，支持全选/取消全选及局部节点勾选。
*   **并发克隆**：内置多线程支持（并发数控制为 5），极大提升多个项目的克隆速度。
*   **协议支持**：支持 `HTTPS` 和 `SSH` 两种克隆方式。
*   **进度监控与错误重试**：实时展示克隆进度、成功/失败/已存在的状态及耗时，并且支持一键重试失败的项目。
*   **目录防覆盖**：若本地对应的目标路径下已存在文件夹，会自动跳过克隆并标记为“已存在”。
*   **轻量化依赖**：仅需系统安装 Git，使用 Python 原生库编写，支持一键打包为单执行文件 (exe)。

#### 软件架构
本工具采用 Python 构建，核心模块划分为：
*   **UI 模块 (`ui/`)**：基于 Python 标准库 `tkinter` 及 `ttk` 构建界面，包含配置区 (`config_frame`)、树形项目选择区 (`tree_frame`) 以及克隆进度列表区 (`clone_frame`)。
*   **GitLab API 客户端 (`gitlab_client.py`)**：使用 Python 内置的 `urllib`，负责与 GitLab API 通信，递归抓取项目列表并构建嵌套树状结构数据。
*   **克隆引擎 (`cloner.py`)**：通过 Python 内置的 `subprocess` 调用系统 `git` 命令，利用 `threading` 与 `Queue` 控制并发执行，通过回调更新界面状态。
*   **配置模块 (`config.py`)**：负责读取与持久化存储 Token 等配置信息至 `~/.gitclonetool/config.json`。

#### 安装教程

**方式一：直接运行源码**
1.  确保系统已安装 **Python 3.10+**（安装时需勾选 tcl/tk 以支持 tkinter）以及 **Git**。
2.  克隆或下载本仓库代码到本地。
3.  进入 `gitlab-clone-tool-py` 目录：
    ```bash
    cd gitlab-clone-tool-py
    ```
4.  安装依赖库（主要是打包和测试用到，运行本身只依赖标准库）：
    ```bash
    pip install -r requirements.txt
    ```
5.  启动程序：
    ```bash
    python main.py
    ```

**方式二：打包为单执行文件 (Windows)**
如果你想将其打包成一个独立的 `exe` 文件方便分发使用，可以使用 PyInstaller 进行打包：
1.  在 `gitlab-clone-tool-py` 目录下执行打包命令：
    ```bash
    pyinstaller --onefile --windowed --name "gitlab-clone-tool" main.py
    ```
2.  打包完成后，在 `dist/` 目录下找到 `gitlab-clone-tool.exe`。将该文件发送给其他人即可使用（前提是使用者的系统已安装并在 PATH 中配置了 git）。

#### 使用说明

1.  **填写配置**：
    *   **GitLab 地址**：填写 GitLab 服务的根 URL（如：`https://gitlab.example.com`）。
    *   **Token**：填写具有读取项目权限的 Private Token/Personal Access Token。
    *   **组名**：输入你要克隆的最顶层组路径（如 `mygroup` 或 `frontend/web`）。
    *   **本地目录**：点击“浏览”选择克隆文件存放的本地根目录。
    *   **克隆方式**：根据需求选择 `SSH` 或 `HTTPS`。
2.  **连接 GitLab**：
    点击“连接”按钮，工具将调用 API 拉取指定组名下的所有子组和仓库，并以树形结构加载在“选择项目”区域。
3.  **选择项目**：
    在树形视图中勾选你所需要克隆的项目，支持“全选”和“取消全选”。
4.  **开始克隆**：
    点击“开始克隆”，工具将在下方“克隆进度”区显示实时的克隆状态（排队、克隆中、完成、失败、已存在）。
5.  **失败重试**：
    如果出现由于网络抖动或其他原因导致个别项目克隆失败，点击“重试失败项”按钮即可针对失败的仓库重新执行。

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request

#### 注意事项
1.  **Git 环境**：本工具依赖操作系统的 `git` 命令，运行前请务必确保 `git` 已安装并且将其配置到了系统环境变量 `PATH` 中。
2.  **SSH 密钥**：如选择 SSH 克隆方式，请确保本机已配置对应的 GitLab SSH Key 且无密码交互阻挡。
3.  **防毒软件误报**：使用 PyInstaller 编译出来的 `exe` 文件有时可能被 Windows Defender 或其他杀毒软件误报为可疑文件，可添加白名单放行。