Bundles, Mirrors, Repository Migration, Archival, and Offline Transfer: Configuration, Design Choices, and Tradeoffs

1. Migration policy must name the authoritative source and the allowed direction

A mirror relationship is powerful precisely because it can overwrite and delete refs. Document which repository is authoritative, which endpoint is a replica, who can initiate synchronization, and when pruning/deletion is allowed. Never rely on a remote name such as origin to imply authority.

2. Inspect mirror configuration with origin/scope evidence

git remote -v
git config --show-origin --get-all remote.origin.fetch
git config --show-origin --get remote.origin.mirror
git config --show-origin --get remote.origin.prune
git config --show-origin --get fetch.prune
git for-each-ref --sort=refname --format='%(refname) %(objectname)'

Configuration can come from system, global, local, worktree, command-line -c, and environment-driven mechanisms. A migration runbook should capture effective values, not merely the repository-local file.

3. Fetch mirrors and push mirrors are different directions

A clone made with --mirror configures fetch behavior so source refs map to same-named local refs. Separately, a remote can be configured with --mirror=push, making mirror behavior the default push policy for that remote. Keep those directions explicit:

git remote add --mirror=fetch upstream /path/to/source.git
git remote add --mirror=push destination /path/to/destination.git

4. Pruning is necessary for exact mirrors and dangerous for mixed-purpose repositories

Fetch pruning removes local destinations that no longer have a mapped source ref. With broad mirror refspecs, the affected set is broad: it can include tags, notes, and custom namespaces—not only stale remote-tracking branches.

git remote update --prune origin
# or:
git fetch --prune origin

That is appropriate only when the local repository is an intentional replica and no local-only refs are supposed to survive.

5. Full bundles optimize portability; incremental bundles optimize transfer size

A self-contained bundle is easiest to recover because it has no prerequisites. An incremental bundle excludes old history and depends on the recipient already possessing the excluded objects.

# Self-contained selected history:
git bundle create bootstrap.bundle trunk

# Incremental update after recording a common point:
git bundle create update.bundle last-transfer..trunk

The incremental bundle is smaller when little has changed, but operational cost rises because you must track the prerequisite boundary and verify it on every recipient.

6. Use a named common point and verify on the recipient

# Producer after a successful bootstrap transfer:
git tag last-transfer trunk

# Later:
git bundle create update.bundle last-transfer..trunk

# Recipient:
git bundle verify /path/to/update.bundle
git fetch /path/to/update.bundle trunk:refs/remotes/offline/trunk

The tag is a coordination marker, not magic. If the recipient lost prerequisite objects or never received the bootstrap, verification will fail. Erring on the side of including extra objects is usually safer than creating a too-thin transfer.

7. Bundle format and object format are version-sensitive

Current Git documentation distinguishes bundle format versions and repository hash algorithms. Do not hard-code 40-character object IDs or force a bundle version unless compatibility requirements justify it. Let Git choose a supported default and record git --version plus the bundle verification output.

8. Git LFS needs a dedicated migration inventory

Before cutover, verify whether Git LFS is installed and used:

git lfs version
git lfs ls-files
git lfs env

For backup/migration, official Git LFS documentation provides git lfs fetch --all to download all referenced LFS objects into the local cache. How those objects are uploaded to a new server depends on the destination's LFS endpoint and authentication. A Git ref mirror alone is not enough.

9. Do not confuse LFS transfer with LFS history migration

git lfs migrate import/export can rewrite history and change commit IDs. That is a separate change-management project requiring clean working state, backup, validation, and coordinated ref updates. If the migration goal is merely “move the same repository to another server,” avoid rewriting object identity unless explicitly required.

10. Every submodule repository needs its own transfer and access plan

git submodule status
git config --file .gitmodules --get-regexp '^submodule\..*\.url$'

The superproject records a gitlink commit plus a URL hint. Validate that each destination submodule server contains the referenced commit and that the post-cutover URLs resolve correctly. Relative URLs can be helpful when the repositories move together, but they must be tested against the new repository layout.

11. Server-side hooks and repository policy are external dependencies

A bare/mirror copy does not automatically reproduce hosting settings, access-control databases, required checks, protected refs, merge rules, deploy keys, webhooks, CI variables, or custom server hooks. Inventory them as separate migration workstreams with owners and validation evidence.

12. Hosted issues, PR/MR discussions, releases, and packages need platform APIs/tools

Core Git transfers commits/trees/blobs/tags and refs. Hosted issues, review threads, release objects, package registries, and workflow histories are service data. Migrate them only if the project requires them, using the provider's documented export/import/API mechanisms rather than assuming a mirror covers them.

13. Offline media needs confidentiality and integrity controls

A bundle can contain full source history, including sensitive material that remains reachable. Treat offline media like a backup: restrict access, encrypt at the storage/container layer when policy requires it, record checksums using an approved cryptographic hash tool, retain a custody log, and securely retire obsolete copies according to policy.

14. Checksum policy protects the transfer artifact, not repository authorization

sha256sum full.bundle > full.bundle.sha256
sha256sum --check full.bundle.sha256

On PowerShell, Get-FileHash -Algorithm SHA256 full.bundle provides the equivalent artifact-integrity measurement. A matching checksum proves the bundle bytes match the recorded bytes; it does not prove the commits are authorized or safe.

15. Define retention and rollback lifetime

Keep the old source read-only until the destination has passed ref/object, LFS/submodule, permission, hook/policy, and client/CI validation. Retention must balance rollback value against security obligations: old mirrors and bundle files can contain credentials or proprietary history even after the active repository has been remediated.

16. Decision table

17. Knowledge check

18. Summary

Operational migration policy names authority and direction, controls pruning, distinguishes full from prerequisite-based bundles, treats LFS/submodules/server metadata as separate dependencies, secures offline media, and keeps rollback artifacts long enough to validate the new system.

Authoritative references

• git-fetch pruning
• git-bundle prerequisites
• gitsubmodules
• git-lfs-fetch
• git-lfs-migrate