gitload

# gitload

使用 gitload CLI 从 GitHub URL 下载文件、文件夹或整个仓库。

## 适用场景

在以下情况下使用 gitload： - 仅从仓库下载特定文件夹（而非整个仓库） - 从 GitHub 获取单个文件 - 不含 git 历史记录地下载仓库内容 - 创建 GitHub 内容的 ZIP 归档 - 通过认证访问私有仓库

请勿在以下情况下使用 gitload： - 需要完整的 git 历史记录（请改用 `git clone`） - 仓库已在本地克隆 - 使用非 GitHub 的仓库

## 前置条件

通过 npx 运行 gitload（无需安装）： ```bash npx gitload-cli https://github.com/user/repo ```

或者全局安装： ```bash npm install -g gitload-cli ```

## 基本用法

### 下载整个仓库 ```bash gitload https://github.com/user/repo ``` 在当前目录中创建 `repo/` 文件夹。

### 下载特定文件夹 ```bash gitload https://github.com/user/repo/tree/main/src/components ``` 创建 `components/` 文件夹，其中仅包含该文件夹的内容。

### 下载单个文件 ```bash gitload https://github.com/user/repo/blob/main/README.md ```

### 下载到自定义位置 ```bash gitload https://github.com/user/repo/tree/main/src -o ./my-source ```

### 将内容扁平化下载到当前目录 ```bash gitload https://github.com/user/repo/tree/main/templates -o . ```

### 下载为 ZIP ```bash gitload https://github.com/user/repo -z ./repo.zip ```

## 身份验证（用于私有仓库或速率限制）

### 使用 gh CLI（推荐） ```bash gitload https://github.com/user/private-repo --gh ``` 需提前执行 `gh auth login`。

### 使用显式 token ```bash gitload https://github.com/user/repo --token ghp_xxxx ```

### 使用环境变量 ```bash export GITHUB_TOKEN=ghp_xxxx gitload https://github.com/user/repo ```

**Token 优先级：** `--token` > `GITHUB_TOKEN` > `--gh`

## URL 格式

gitload 接受标准的 GitHub URL： - **仓库根目录：** `https://github.com/user/repo` - **文件夹：** `https://github.com/user/repo/tree/branch/path/to/folder` - **文件：** `https://github.com/user/repo/blob/branch/path/to/file.ext`

## 常见用法模式

### 从模板文件夹构建项目 ```bash gitload https://github.com/org/templates/tree/main/react-starter -o ./my-app cd my-app && npm install ```

### 获取示例代码 ```bash gitload https://github.com/org/examples/tree/main/authentication ```

### 下载文档供离线阅读 ```bash gitload https://github.com/org/project/tree/main/docs -z ./docs.zip ```

### 获取单个配置文件 ```bash gitload https://github.com/org/configs/blob/main/.eslintrc.json -o . ```

## 选项参考

| 选项 | 描述 | |--------|-------------| | `-o, --output <dir>` | 输出目录（默认：以 URL 路径命名的文件夹） | | `-z, --zip <path>` | 将内容作为 ZIP 文件保存到指定路径 | | `-t, --token <token>` | GitHub 个人访问令牌 | | `--gh` | 使用 gh CLI 中的令牌 | | `--no-color` | 禁用彩色输出 | | `-h, --help` | 显示帮助信息 | | `-V, --version` | 输出版本号 |

## 错误处理

如果 gitload 失败： 1. **404 错误：** 验证 URL 是否存在且可访问 2. **速率限制错误：** 使用 `--gh` 或 `--token` 添加身份验证 3. **权限错误：** 对于私有仓库，请确保 token 具有 `repo` 作用域 4. **网络错误：** 检查互联网连接

## 注意事项

- gitload 通过 GitHub API 下载内容，而非 git 协议 - 不保留 git 历史记录（如需历史记录，请使用 `git clone`） - 大型仓库可能需要较长时间；考虑下载特定文件夹 - 如果输出目录不存在，将会自动创建