Bundles, Mirrors, Repository Migration, Archival, and Offline Transfer: Diagnostics, Failure Modes, Security, and Performance

1. Migration diagnostic sequence

1. Preserve evidence: source/destination ref snapshots, immutable commit IDs, bundle files/checksums, logs, current URLs, and configuration.
2. Inspect: refs, advertised refs, bundle prerequisites, LFS/submodule state, remote URLs, and server/hosting policy.
3. Classify the layer: ref mapping, object availability, external LFS/submodule content, platform metadata, access control, or source-tree packaging.
4. Choose the least destructive correction.
5. Verify again before any cutover or cleanup.

2. Intentionally broken example — mirror push points at the wrong destination

Construct a disposable wrong destination containing a ref that must survive:

git init --bare -b trunk wrong-destination.git
git clone wrong-destination.git wrong-writer
git -C wrong-writer config user.name "Wrong Destination Owner"
git -C wrong-writer config user.email "owner@example.invalid"
printf "do-not-delete\n" > wrong-writer/sentinel.txt
git -C wrong-writer add sentinel.txt
git -C wrong-writer commit -m "sentinel branch"
git -C wrong-writer push origin HEAD:refs/heads/do-not-delete

git -C mirror-copy.git remote add wrong ../wrong-destination.git
git -C mirror-copy.git push --mirror --dry-run --porcelain wrong

Expected dry-run evidence includes a deletion for refs/heads/do-not-delete because that destination ref does not exist in the mirror. Do not run the real push.

3. Interpret the broken output line by line

A mirror dry-run can report new refs, forced updates, unchanged refs, and deletions. The deletion is not a warning about an unrelated branch; it is the exact mirror contract: remote refs under refs/ absent locally are candidates for removal.

git -C mirror-copy.git remote get-url wrong
git -C wrong-destination.git for-each-ref --sort=refname \
  --format='%(refname) %(objectname)'
git -C mirror-copy.git for-each-ref --sort=refname \
  --format='%(refname) %(objectname)'

Repair the cause by fixing the destination selection, not by adding arbitrary force flags. Remove or correct the erroneous migration remote and repeat the dry run against the intended disposable target.

4. Failure mode — incremental bundle sent to a repository missing prerequisites

# Producer:
git tag transfer-base trunk~1
git bundle create ../incremental.bundle transfer-base..trunk

# Empty recipient:
git init --bare -b trunk empty-recipient.git
git -C empty-recipient.git bundle verify ../incremental.bundle
echo "verify exit=$?"

Expected: non-zero verification and a report that prerequisite commit(s) are missing. That is not bundle corruption; it is a recipient-state mismatch. Repair by first supplying a self-contained bootstrap/history that contains the prerequisite, then re-run verification.

5. Failure mode — treating a tar/ZIP as repository backup

git archive --format=tar -o source-only.tar trunk
mkdir source-only
tar -xf source-only.tar -C source-only
git -C source-only log --oneline
echo "exit=$?"

The failure is expected because the archive has no Git metadata. The correction is not “add a .git folder by hand”; create a bundle/bare/mirror backup according to the recovery requirement.

6. Failure mode — migration validates branches but silently loses notes/custom refs

A branch-only checklist can report success while code-review notes or release metadata refs vanish. Always compare the full intended namespace:

git -C source for-each-ref --sort=refname \
  --format='%(refname) %(objectname)'
git -C destination.git for-each-ref --sort=refname \
  --format='%(refname) %(objectname)'

git -C source notes list
git -C destination.git notes list

7. Failure mode — assuming “mirror” means every server-internal ref

A remote can expose only the refs the server advertises and authorizes. Server configurations may intentionally hide internal namespaces. If a migration requires hidden service refs, use the server/vendor's supported administrative export path rather than assuming client-side clone --mirror can see them.

8. Failure mode — Git refs migrated, LFS downloads fail

Symptoms: commits and pointer files exist, but checkout reports missing LFS objects or leaves pointer content. Diagnose:

git lfs version
git lfs env
git lfs ls-files
git lfs fetch --all origin

If Git LFS is absent, the command itself fails—another migration dependency to record. If the source LFS endpoint lacks objects, mirroring Git refs cannot recreate them. Restore/upload from a validated LFS backup or source endpoint.

9. Failure mode — superproject migrated but submodule commit is unavailable

git submodule status
git config --file .gitmodules --get-regexp '^submodule\..*\.url$'
git ls-tree HEAD path/to/submodule

The gitlink can point to a commit that the new submodule server does not contain. Validate the referenced OID in the migrated submodule repository before declaring the superproject cutover complete.

10. Failure mode — clone/mirror succeeded but project operations are incomplete

Missing pull-request discussions, branch protection, hosted releases, deployment keys, CI variables, or package artifacts are not Git-object corruption. They are omitted platform state. Correct them through platform-specific migration/configuration workstreams and record acceptance tests separately.

11. Ref count alone is insufficient

Two repositories can have the same number of refs while different names point to different objects. Compare full refname + objectname snapshots. Likewise, object count alone can differ because of unreachable objects or auxiliary packing while all intended reachable history matches.

12. Security relevance — migrations duplicate sensitive history

Bundles, mirrors, and offline disks can create extra copies of credentials or proprietary history. A migration does not sanitize old commits. If secrets are discovered, follow the Chapter 21 incident path: revoke/rotate first, preserve evidence, plan history remediation separately, and control every copied artifact.

13. Performance relevance — size determines transfer strategy, not correctness

Large repositories may benefit from incremental bundles, local network staging, LFS-aware transfer, or server-side migration tools. Optimize transfer time only after preserving completeness checks. A smaller bundle that omits required prerequisite history is not an optimization.

14. Red-zone operations

15. Symptom → layer → safe next evidence

16. Knowledge check

17. Summary

Migration diagnostics preserve evidence first. The most dangerous failures are often policy mistakes—wrong destination, wrong ref scope, missing prerequisite assumptions, or omitted external stores—not low-level Git corruption. Dry-run, compare exact refs, validate dependencies, and keep rollback artifacts intact.

Authoritative references

• git-push
• git-bundle
• git-archive
• git-fetch
• git-lfs-fetch