Metadata-Version: 2.4
Name: dump_github
Version: 0.1.8
Summary: This tool can be used to back up users' GitHub repositories in case they need them later.
Home-page: https://github.com/core2002/dump_github
Author: core2002
Author-email: core2002@aliyun.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: argparse
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

### Github Dumper

Github Dumper is a Python program designed to search for users' GitHub repositories and download the repositories. This tool can be used to back up users' GitHub repositories in case they need them later.

**Install:**

```
pip install -U dump-github
```

**Usage:**

```
usage: dump-github [-h] [-d] [-p] [--token TOKEN] [--limit_size LIMIT_SIZE] username

Backup users github repo.

positional arguments:
  username

options:
  -h, --help            show this help message and exit
  -d, --download_zip    only download zip file
  -p, --print           only print urls
  --token TOKEN         GitHub personal access token (or set GITHUB_TOKEN)
  --limit_size LIMIT_SIZE
                        limit size(MB) of download zip file, if 0 then no limit(default:100).

https://github.com/Core2002/dump_github
```

### Authentication (token)

GitHub’s API requires a proper `Authorization: Bearer <token>` header. This tool accepts a **personal access token** in two ways (first match wins):

1. **`--token`** on the command line  
2. **`GITHUB_TOKEN`** environment variable (if `--token` is empty)

**Why use a token?**

- **Private repositories**: Without a token, only public repos are listed and can be cloned or archived. With a token that has the right scopes, you can include private repos you are allowed to access (for example when backing up your own account).
- **Rate limits**: Authenticated API requests get a much higher limit than anonymous requests.

**How the token is used**

- **Listing repos** (`GET /users/{username}/repos`): sent as `Bearer` on the REST API.
- **Clone** (default mode): HTTPS clone URL is turned into `https://x-access-token:<token>@github.com/...` so `git clone` can access private repos.
- **Zip download** (`-d`): uses the [repository archive (zipball)](https://docs.github.com/en/rest/repos/repos#download-a-repository-archive-zip) API with the same `Bearer` header (via `curl`), which works for private repos; without a token, public archive URLs are used instead.

Create a token under GitHub → **Settings** → **Developer settings** → **Personal access tokens**. For private repo backup, enable access to **repository contents** (classic PAT: `repo` scope; fine-grained: read access to the repositories you need).

**Examples**

```bash
# Public repos only (no token)
dump-github Core2002 -p

# Token on the command line (private + higher API limits)
dump-github username --token ghp_xxxxxxxxxxxx

# Same, via environment variable (recommended to avoid shell history)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
dump-github Core2002 -d
```

**Security note:** Do not commit tokens or paste them into shared logs. Prefer `GITHUB_TOKEN` in a local shell profile or a secret manager, and rotate the token if it leaks.
