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): ```bash npx gitload-cli https://github.com/user/repo ```

Or install globally: ```bash npm install -g gitload-cli ```

## Basic Usage

### Download entire repo ```bash gitload https://github.com/user/repo ``` Creates a `repo/` folder in the current directory.

### Download a specific folder ```bash gitload https://github.com/user/repo/tree/main/src/components ``` Creates a `components/` folder with just that folder's contents.

### Download a single file ```bash gitload https://github.com/user/repo/blob/main/README.md ```

### Download to a custom location ```bash gitload https://github.com/user/repo/tree/main/src -o ./my-source ```

### Download contents flat to current directory ```bash gitload https://github.com/user/repo/tree/main/templates -o . ```

### Download as ZIP ```bash gitload https://github.com/user/repo -z ./repo.zip ```

## Authentication (for private repos or rate limits)

### Using gh CLI (recommended) ```bash gitload https://github.com/user/private-repo --gh ``` Requires prior `gh auth login`.

### Using explicit token ```bash gitload https://github.com/user/repo --token ghp_xxxx ```

### Using environment variable ```bash 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 ```bash gitload https://github.com/org/templates/tree/main/react-starter -o ./my-app cd my-app && npm install ```

### Grab example code ```bash gitload https://github.com/org/examples/tree/main/authentication ```

### Download docs for offline reading ```bash gitload https://github.com/org/project/tree/main/docs -z ./docs.zip ```

### Fetch a single config file ```bash 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