Repository history rewrite

Goal

Optimize clone/fetch performance by flattening repository history and reducing historical object payload while preserving maintainer attribution.

Chosen Flattening Mode

• Mode: single-commit snapshot (maximum pack-size reduction)
• Why: this repository contains large historical binary artifacts; flattening to a single root commit yields the largest transfer reduction.
• Maintainer preservation strategy: preserve full pre-flatten attribution in the unlisted maintainer history manifest.

Pre-Cutover Inputs

1. Ensure full history is present (git fetch --unshallow origin when required).
2. Generate baseline artifacts and manifest:

   scripts/maintenance/flatten-history.sh

3. Review baseline files in /tmp/shaft-history-rewrite/:
   • pre-maintainers-shortlog.txt
   • pre-identities-raw.txt
   • pre-largest-blobs.txt
   • pre-count-objects.txt
   • pre-dotgit-size.txt

Retention / Removal Policy

• Retain: current main tree content needed for build/test/runtime/docs.
• Remove from history: all prior commit graph and unreachable historical blobs.
• Result: new history starts from one fresh root commit, with maintainer attribution preserved in manifest.

Execute Local Rewrite

TARGET_BRANCH=main \
FLATTEN_BRANCH=history/flattened-main \
scripts/maintenance/flatten-history.sh --execute

The script auto-configures a local fallback git identity when user.name/user.email are not set. You can override rewrite commit identity explicitly with GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL.

Validation Checklist

• Maintainer manifest is published in the documentation archive.
• Object/pack improvement:

  git count-objects -vH
  du -sh .git

• Clone benchmark (same runner, no local hardlink optimization):

  /usr/bin/time -f '%E real' git clone --no-local <repo-url> /tmp/clone-baseline
  /usr/bin/time -f '%E real' git clone --no-local <rewritten-repo-url> /tmp/clone-rewritten

• Ref/tag integrity review completed (release tags preserved only if intentionally recreated).
• Example measured results are retained in the history rewrite validation record.

Maintainer Cutover Procedure (Force Push)

1. Announce maintenance window and temporary push freeze.
2. Create remote backup mirror before cutover:

   git clone --mirror <repo-url> /tmp/repo-backup-mirror.git

   Replace <repo-url> with the full repository URL, for example: https://github.com/ShaftHQ/SHAFT_ENGINE.git.
3. Push rewritten branch to a staging remote for verification.
4. After approval, force-update protected default branch (maintainer operation only).
5. Broadcast migration instructions to contributors:

   git fetch --all --prune
   git switch main
   git reset --hard origin/main
   git gc --prune=now

Rollback Plan

• Keep backup mirror and pre-flatten backup ref until stability checks complete.
• If rollback is required, force-push backup mirror/ref back to default branch.
• Re-run post-rollback verification (tags, CI pipelines, release automation).