Repository Slimming and Branch Cleanup

On June 23, 2026, we performed a cleanup of the repository infrastructure. This involved two tasks: deployment architecture migration (gh-pages branch → GitHub Actions artifact deployment) and decommissioning legacy archive branches (archive/legacy_20260415). The net effect: a fresh clone dropped from ~500MB to 19MiB, remote branches converged to only main, and the documentation site address and content remained unchanged. This log records the motivation, changes, results, and pitfalls encountered during the process.

1. Deployment Migration: gh-pages Branch → Actions Artifact Deployment

Background: Why the Repository Bloated to ~500MB

The old deployment used a third-party action, peaceiris/actions-gh-pages, which committed the entire build artifact to the gh-pages branch on every deployment. The root cause lay in VitePress's local search index chunks (@localSearchIndexroot.*.js): these are content-addressed, meaning every build generates a new hash. Each chunk is about 8–10MB, and every deployment shoved a new copy into gh-pages history. Over time:

• History accumulated 90 such blobs, totaling ~437MB
• This accounted for 86% of the total .git size (the whole repo was ~500MB)
• This 437MB was 100% isolated in the gh-pages branch; the main branch remained clean (0 search index blobs in git rev-list --objects main)

Changes

We switched to the official GitHub artifact deployment trio: build artifacts are deployed as one-time artifacts, discarded after use, and no longer committed to any branch. From now on, the search index chunk from each build is just a regular file inside the artifact, no longer polluting history.

• actions/configure-pages@v5 → actions/upload-pages-artifact@v3 → actions/deploy-pages@v4
• Split into build/deploy jobs, permissions: pages: write + id-token: write
• Preserved sharded parallel build cache (.build-cache), NODE_OPTIONS=--max-old-space-size=6144 to prevent OOM, and fetch-depth: 0 (required by lastUpdated for full history).

The deployment configuration is in .github/workflows/deploy.yml at the repository root.

Results

git clone pulls all branches by default. Before migration, it downloaded that 437MB via the gh-pages branch. After branch deletion and server-side gc, a fresh clone showed:

Metric	Before Migration	After Migration
Clone Transfer Size	~500 MB	19 MiB
Local Disk Usage (Workspace + .git)	~500 MB	47 MB

Pitfalls Encountered (For the Record)

1. Environment Branch Protection: After switching to GitHub Actions deployment, the built-in branch_policy for the github-pages environment only whitelisted gh-pages. The deploy job failed instantly (Branch main is not allowed to deploy to github-pages due to environment protection rules). Fix: Added main to the environment's deployment branch policies.
2. Pages Source Not Switched Can "Half-Work": When the Source was still Deploy from a branch: gh-pages, deployments generated by actions/deploy-pages would override the branch source, and the site would run normally. However, this is a fragile state where appearance and reality do not match. You must switch Settings → Pages → Source to GitHub Actions—this is also a prerequisite for safely deleting the gh-pages branch (otherwise deleting it breaks the site).
3. gh api .../size Field Lags Severely: After migration and gc, this field still showed ~500MB for a long time and barely updated. Treat the fresh clone transfer size as the only trusted evidence; do not trust the size field.

2. Branch Cleanup: Removing archive/legacy_20260415

What It Was

archive/legacy_20260415 was an archive branch from before the repository architecture refactor on April 15, 2026. It was marked as "Pre-refactor archive / Read-only" and used during the refactor to preserve the old state for potential rollback.

Why We Can Delete It Now

The refactor is long complete and stable, and main is the single source of truth. Verification: git rev-list --count archive/legacy_20260415 ^main = 0. This means the branch tip (993e8d0) is an ancestor commit within main's history. All objects are shared with main, so deleting it releases 0 objects. In other words, its content is already fully preserved in main's history; keeping it was just noise in the branch list.

Impact

This is purely a hygiene cleanup. It does not affect repository size (size benefits come entirely from the gh-pages change) and does not affect any content.

3. Net Effect

• Remote branches: main + gh-pages + archive/legacy_20260415 → Only main remains
• Repository size: Fresh clone ~500MB → 19MiB transfer / 47MB disk usage
• Documentation site: Address, content, links, and SEO remain completely unchanged

4. Impact on Contributors

The site and contribution workflow received a seamless upgrade. If you have an old local clone (where .git is still ~500MB), you may optionally slim it down:

git fetch --prune origin
git gc --prune=now --aggressive

Or simply re-clone the repository (now it is only 19 MiB). This step is completely optional; skipping it will not affect normal usage.