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