xgit-utils

用于克隆和同步 Git 镜像仓库，以及列出或导出 GitHub 仓库的命令行工具。

环境要求

• Python 3.10 或更高版本
• 已安装 Git，且 Git 命令位于 PATH 中
• 使用 xgithub 命令时需要 GitHub Personal Access Token

安装

使用 pip 安装：

python -m pip install xgit-utils

也可以使用 pipx 安装，以隔离命令行工具的运行环境：

pipx install xgit-utils

安装后可使用四个命令：xgit（命令组）、xclone、xsync 和 xgithub。每个命令都支持 --help，可查看完整参数列表。独立命令与 xgit 子命令的功能相同。

克隆仓库

克隆单个仓库：

xclone https://github.com/owner/repository.git

从文本文件中逐行读取并克隆仓库（每行一个URL，空行会被忽略）：

xclone repos.txt --target-dir ~/Mirror/github

也可以使用命令组：

xgit clone repos.txt

仓库会以 Git mirror 形式克隆到目标目录，并按 URL 路径分组。默认目标目录为 ~/Mirror/github，可通过 --target-dir 指定其他位置。

传入 --ignore 后，程序会将给定的 URL 写入 ~/.xgit/.xgitignore，而不执行克隆。之后克隆时会跳过该文件中列出的 URL。

同步仓库

获取目标目录下所有镜像仓库的更新：

xsync

常用参数：

xsync --repo okhttp                  # 只同步 URL 中包含“okhttp”的仓库
xsync --filter-host github.com        # 只同步来自该主机的仓库
xsync --filter-host github.com --filter-host gitlab.com
xsync --list-remote                   # 列出本地镜像中的远程主机
xsync --list-repo                     # 列出本地镜像及其占用空间
xsync --export                        # 将仓库 URL 导出到文本文件
xsync --thread 4                      # 设置并发同步数

默认目标目录为 ~/Mirror/github，默认线程数为 6。也可以通过 xgit sync 使用这些参数。

管理 GitHub 仓库

建议将 Token 设置为环境变量，避免保存在 shell 命令历史中：

export GITHUB_TOKEN="your-token"

列出已加星标的仓库（默认操作）：

xgithub

列出自己的仓库或指定用户的仓库：

xgithub --mine
xgithub --user octocat

将自己的仓库克隆到目标目录，或将所选仓库列表导出为 HTML 文件（保存到当前目录）：

xgithub --mine --clone
xgithub --user octocat --export

也可以通过 --token 直接传入 Token。通常使用 GITHUB_TOKEN 环境变量更方便。也可以通过 xgit github 使用这些参数。

代理

所有命令都支持 --use-proxy（或 -u）和 --proxy（或 -p）。默认代理地址为 127.0.0.1:1087：

xclone repos.txt --use-proxy --proxy 127.0.0.1:1087

开发

安装项目及开发依赖：

python -m pip install -e ".[dev]"

使用 Black 格式化 Python 代码：

python -m black .

仓库中的 VS Code 设置会选用 Black Formatter，并在保存 Python 文件时自动格式化。Black 的行宽配置读取自 pyproject.toml。

构建源码分发包和 wheel：

python -m build