Problem: Downloading GitHub zip/tarball keeps timing out and breaking —— Trove problem library

What you will run into

Downloading a zip/tarball from GitHub repeatedly times out and breaks; you never get a complete archive. It cuts at 80%, retries still cut — you start suspecting the package is too big — it's usually a link problem.

Why this happens

The download link to GitHub (codeload/github.com) is unstable or low-bandwidth; large transfers break midway. Not the package's problem — it's the channel's.

A download is essentially "one URL, one channel": the same content has multiple exits on GitHub — tarballs via codeload, raw files via the raw endpoint, repo content via the git protocol.

These exits have different domains, CDNs and link quality, and behave very differently behind the GFW: codeload can be stable while raw times out (exactly what was measured in this marketplace).

So on "download failed", the first reaction shouldn't be "package too big / network all broken" but switch channels: tarball breaks -> try a git shallow clone (git protocol, latest commit only, smaller); clone breaks -> try the tarball.

The two channels are independent — one being bad doesn't mean all are.

Verifying completeness also has a fixed method: extraction without errors (streamed tarball extraction) or a complete directory structure (clone).

The general principle underneath: multiple exits for the same resource back each other up; don't retry the same broken channel over and over.

Step by step

1. Switch channels — Required

Tarball download breaks → try a git shallow clone; clone breaks → try the tarball. Swapping between the two often dodges a bad link.

2. Switch networks / enable a proxy — Required

Retry after changing network environment or enabling a proxy; retry off-peak.

3. Offline extraction — Required

Download the zip from any reachable mirror → extract manually → wire in via the local-path method; an alternative that doesn't depend on zip integrity = take only the skills directory (it's inside the tarball).

How to confirm it works

Download complete and extraction succeeds (measured shape):

curl -sL https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 | tar xz
→ extracted with no errors (measured 544K / 2.1s)

Or git clone --depth 1 finishes normally with complete directory structure.

Other environments

Symptom

Downloading the zip / tarball from GitHub repeatedly times out or interrupts; the archive never completes.

Cause

The download path to GitHub (codeload/github.com) is unstable or low-bandwidth; large transfers drop mid-way.

Solution

1. Switch channel: use git clone (shallow: git clone --depth 1 --branch v6.3.0 https://github.com/obra/superpowers.git) or the reverse.
2. Switch network: change network / enable proxy and retry; retry off-peak.
3. Offline extraction: download the zip from any reachable mirror -> extract manually -> wire it in per Symptom 6; a zip-integrity-independent alternative = take only the skills directory (included in the tarball).