gitload

gitload

Download files, folders, or entire repos from GitHub URLs using the gitload CLI.

When to Use

Use gitload when:

• Downloading a specific folder from a repo (not the whole repo)
• Fetching a single file from GitHub
• Downloading repo contents without git history
• Creating a ZIP archive of GitHub content
• Accessing private repos with authentication

Do NOT use gitload when:

• Full git history is needed (use git clone instead)
• The repo is already cloned locally
• Working with non-GitHub repositories

Prerequisites

Run gitload via npx (no install needed):

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

Or install globally:

npm install -g gitload-cli

Basic Usage

Download entire repo

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

Creates a repo/ folder in the current directory.

Download a specific folder

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

Creates a components/ folder with just that folder's contents.

Download a single file

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

Download to a custom location

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

Download contents flat to current directory

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

Download as ZIP

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

Authentication (for private repos or rate limits)

Using gh CLI (recommended)

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

Requires prior gh auth login.

Using explicit token

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

Using environment variable

export GITHUB_TOKEN=ghp_xxxx
gitload https://github.com/user/repo

Token priority: --token > GITHUB_TOKEN > --gh

URL Formats

gitload accepts standard GitHub URLs:

• Repo root: https://github.com/user/repo
• Folder: https://github.com/user/repo/tree/branch/path/to/folder
• File: https://github.com/user/repo/blob/branch/path/to/file.ext

Common Patterns

Scaffold from a template folder

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

Grab example code

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

Download docs for offline reading

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

Fetch a single config file

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

Options Reference

Option	Description
-o, --output <dir>	Output directory (default: folder named after URL path)
-z, --zip <path>	Save as ZIP file at the specified path
-t, --token <token>	GitHub personal access token
--gh	Use token from gh CLI
--no-color	Disable colored output
-h, --help	Display help
-V, --version	Output version

Error Handling

If gitload fails:

1. 404 errors: Verify the URL exists and is accessible
2. Rate limit errors: Add authentication with --gh or --token
3. Permission errors: For private repos, ensure token has repo scope
4. Network errors: Check internet connectivity

Notes

• gitload downloads content via GitHub's API, not git protocol
• No git history is preserved (use git clone if history is needed)
• Large repos may take time; consider downloading specific folders
• Output directory is created if it doesn't exist