gitload 是一个命令行工具,用于从 GitHub URL 下载文件、文件夹或整个仓库。它通过 GitHub 的 API 获取内容,而不是使用 git 协议,因此不会保留 git 历史。
用途
gitload 适用于以下场景:
- 从仓库中下载特定文件夹(而非整个仓库)
- 从 GitHub 获取单个文件
- 下载仓库内容但不包含 git 历史
- 将 GitHub 内容打包为 ZIP 归档
- 通过认证访问私有仓库
不适用场景:
- 需要完整的 git 历史(应使用 git clone)
- 仓库已在本地克隆
- 处理非 GitHub 仓库
使用方式
可以通过 npx 直接运行,无需安装:
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 .
选项参考
-o, --output <dir>:输出目录(默认:以 URL 路径命名的文件夹) -z, --zip <path>:保存为 ZIP 文件到指定路径 -t, --token <token>:GitHub 个人访问令牌 --gh:使用 gh CLI 中的令牌 --no-color:禁用彩色输出 -h, --help:显示帮助 -V, --version:输出版本
错误处理
如果 gitload 失败:
- 404 错误:验证 URL 是否存在且可访问
- 速率限制错误:使用 --gh 或 --token 添加认证
- 权限错误:对于私有仓库,确保 token 具有 repo 权限
- 网络错误:检查网络连接
注意事项
- gitload 通过 GitHub 的 API 下载内容,而非 git 协议
- 不保留 git 历史(如需历史请使用 git clone)
- 大型仓库可能需要较长时间;建议下载特定文件夹
- 如果输出目录不存在,会自动创建