Git Bundle: Back Up and Transfer Repositories Offline

Git bundle is a compact way to move a repository to an offline computer or preserve source history independently of a hosting service. It packages selected Git objects and references into a file that can serve as a clone or fetch source.

This guide follows creation with a restore rehearsal. Examples assume a complete repository with a main branch, rather than a shallow or partial clone. Adapt paths and branch names; prepare destination directories in advance.

1. Define what must be preserved

A repository backup plan should distinguish committed history, uncommitted work, machine configuration, and external data. A bundle covers selected objects and references; it is not a snapshot of the entire working directory.

git status --short
git branch --all
git tag --list
git rev-parse --is-shallow-repository

Decide whether to save unfinished changes separately or commit selected work. Do not use git add . merely to obtain a clean status: secret configuration could enter history. For shallow or partial repositories, prepare the required history and objects and prove that restoration works offline.

2. Create the bundle and inspect references

git bundle create ../project-full.bundle --all
git bundle verify ../project-full.bundle
git bundle list-heads ../project-full.bundle

--all selects all refs in the current repository. It does not refresh the hosting service's latest state. Synchronize according to team policy first when that is the intended backup scope, and inspect the advertised branch/tag list.

Keep the bundle outside the source directory to avoid accidentally committing the backup itself. Use dated or versioned filenames when retaining multiple copies.

3. Restore into a new directory

git clone --branch main ../project-full.bundle ../project-restore
git -C ../project-restore log -5 --oneline
git -C ../project-restore branch --all
git -C ../project-restore fsck --full

git rev-parse main
git -C ../project-restore rev-parse main

The main commit IDs should match if the source has not changed since packaging. A normal clone creates the selected working branch and remote-tracking branches; it does not turn every source branch into a local working branch. The explicit branch option identifies what to check out.

git fsck --full checks object validity and connectivity, not application buildability. Follow Git checks with a build and tests using suitable dependencies and configuration, and inspect important files. A useful restoration must support actual work.

4. Preserve the full reference layout

For mirror-style archival, use another new destination:

git clone --mirror ../project-full.bundle ../project-archive.git
git -C ../project-archive.git show-ref
git -C ../project-archive.git fsck --full

A mirror is bare and has no working tree for editing. It fits reference archival, while a normal clone fits development. Never substitute an existing directory containing unsaved work for this fresh archive destination.

5. Transfer incremental history

If the receiver already has the v1.0 baseline and required ancestry, create an incremental main bundle:

git bundle create ../project-update.bundle v1.0..main

This package has prerequisites and does not replace the initial full copy. On the receiving computer, place it next to the restored repository and run:

git -C ../project-restore bundle verify ../project-update.bundle
git -C ../project-restore fetch ../project-update.bundle main:refs/remotes/offline/main
git -C ../project-restore log --oneline main..refs/remotes/offline/main
git -C ../project-restore diff main...refs/remotes/offline/main

This fetch updates a separate tracking reference for review before integration. After checking the working tree and selecting the right branch, follow the team's merge process. Running git merge --ff-only refs/remotes/offline/main on main refuses divergent history. Do not force an overwrite to hide missing prerequisites or divergence.

6. Handle Git LFS and submodules separately

Git LFS stores pointers in Git while large file contents live in LFS storage. Possessing pointers does not mean an offline computer has the actual images, videos, or datasets. Inventory LFS data, transfer the corresponding objects, and test checkout with networking disabled. Retrieval and transfer procedures depend on the team's storage and permissions.

A submodule is a separate repository. Its superproject records the referenced commit and configuration. Prepare a separate bundle or copy for each submodule, including nested ones, and confirm that restored commits match the superproject's expectations.

7. Treat backups as source-code assets

Historical commits can contain sensitive information even when today's files appear clean. Limit access and select appropriate storage. A file checksum detects changes when compared through a trusted channel; alone, it does not authenticate the sender.

An accompanying manifest should record creation time, Git version, target branches/commits, checksum, incremental prerequisites, locations of LFS/submodule data, and restore-test results. This operational recommendation helps another engineer restore without relying on the package creator.

Handover checklist

• Uncommitted work and non-Git files have explicit retention decisions.
• Bundle verification succeeds and refs match the intended scope.
• A fresh clone passes commit comparison and fsck.
• Builds and tests have the required LFS, submodules, and dependencies.
• Incremental bundles have retained and verified prerequisites.
• Ownership, access controls, and periodic restore rehearsals are assigned.

References

git bundle, git clone, git fetch, git fsck, Git submodules, and Git LFS.