gitload

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

适用场景

在以下情况下使用 gitload：

• 从仓库中下载特定文件夹（而非整个仓库）
• 从 GitHub 获取单个文件
• 下载仓库内容但无需 Git 历史记录
• 将 GitHub 内容打包为 ZIP 归档
• 通过身份验证访问私有仓库

请不要在以下情况下使用 gitload：

• 需要完整 Git 历史记录（请改用 git clone）
• 该仓库已在本地克隆
• 操作非 GitHub 仓库

前提条件

可通过 npx 直接运行 gitload（无需安装）：

npx gitload-cli https://github.com/user/repo

或全局安装：

npm install -g gitload-cli

基础用法

下载整个仓库

gitload https://github.com/user/repo

在当前目录下创建名为 repo/ 的文件夹。

下载指定文件夹

gitload https://github.com/user/repo/tree/main/src/components

仅下载该文件夹内容，并在当前目录下创建 components/ 文件夹。

下载单个文件

gitload https://github.com/user/repo/blob/main/README.md

下载到自定义路径

gitload https://github.com/user/repo/tree/main/src -o ./my-source

将内容扁平化下载至当前目录

gitload https://github.com/user/repo/tree/main/templates -o .

以 ZIP 格式下载

gitload https://github.com/user/repo -z ./repo.zip

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

使用 gh CLI（推荐）

gitload https://github.com/user/private-repo --gh

需提前执行 gh auth login 完成登录。

显式传入 token

gitload https://github.com/user/repo --token ghp_xxxx

使用环境变量

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

常见使用模式

基于模板文件夹快速搭建项目

gitload https://github.com/org/templates/tree/main/react-starter -o ./my-app
cd my-app && npm install

获取示例代码

gitload https://github.com/org/examples/tree/main/authentication

下载文档用于离线阅读

gitload https://github.com/org/project/tree/main/docs -z ./docs.zip

获取单个配置文件

gitload https://github.com/org/configs/blob/main/.eslintrc.json -o .

选项参考

错误处理

若 gitload 执行失败，请按以下步骤排查：

1. 404 错误：确认 URL 是否存在且可公开访问
2. 速率限制错误：添加 --gh 或 --token 进行身份验证
3. 权限错误：对于私有仓库，请确保 token 具备 repo 权限范围
4. 网络错误：检查网络连接是否正常

注意事项

• gitload 通过 GitHub API 下载内容，不使用 Git 协议
• 不保留任何 Git 历史记录（如需历史，请使用 git clone）
• 大型仓库下载耗时较长；建议仅下载所需的具体文件夹
• 若输出目录不存在，gitload 将自动创建