Metadata-Version: 2.4
Name: xgit-utils
Version: 2.1.0
Summary: Git repository management tool
Author-email: seven <1162584980@qq.com>
License: MIT License
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyGithub==v2.4.0
Requires-Dist: click
Requires-Dist: tqdm
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: black==24.8.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: types-click; extra == "dev"
Requires-Dist: types-tqdm; extra == "dev"
Provides-Extra: pyinstaller
Requires-Dist: pyinstaller>=6.10.0; extra == "pyinstaller"
Provides-Extra: py2exe
Requires-Dist: py2exe>=0.12; extra == "py2exe"

# xgit-utils

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

## 环境要求

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

## 安装

使用 pip 安装：

```bash
python -m pip install xgit-utils
```

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

```bash
pipx install xgit-utils
```

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

## 克隆仓库

克隆单个仓库：

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

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

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

也可以使用命令组：

```bash
xgit clone repos.txt
```

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

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

## 同步仓库

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

```bash
xsync
```

常用参数：

```bash
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 命令历史中：

```bash
export GITHUB_TOKEN="your-token"
```

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

```bash
xgithub
```

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

```bash
xgithub --mine
xgithub --user octocat
```

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

```bash
xgithub --mine --clone
xgithub --user octocat --export
```

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

## 代理

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

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

## 开发

安装项目及开发依赖：

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

使用 Black 格式化 Python 代码：

```bash
python -m black .
```

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

构建源码分发包和 wheel：

```bash
python -m build
```
