# Repository history rewrite

Maintainer-only procedure for approved repository history rewrites.

Canonical HTML: https://shafthq.github.io/docs/maintainers/history-rewrite
Guide index: https://shafthq.github.io/llms.txt

# 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](/docs/archive/engine/contributors-history).

## Pre-Cutover Inputs
1. Ensure full history is present (`git fetch --unshallow origin` when required).
2. Generate baseline artifacts and manifest:
 ```bash
 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
```bash
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:
 ```bash
 git count-objects -vH
 du -sh .git
 ```
- Clone benchmark (same runner, no local hardlink optimization):
 ```bash
 /usr/bin/time -f '%E real' git clone --no-local /tmp/clone-baseline
 /usr/bin/time -f '%E real' git clone --no-local /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](/docs/archive/engine/history-rewrite-validation).

## Maintainer Cutover Procedure (Force Push)
1. Announce maintenance window and temporary push freeze.
2. Create remote backup mirror before cutover:
 ```bash
 git clone --mirror /tmp/repo-backup-mirror.git
 ```
 Replace ` ` 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:
 ```bash
 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).