Context: When Internet is a Luxury
Back when I was working on a project for a major bank, the entire server was located in an isolated area (air-gapped). No Internet, no external connection to ensure data security. At that time, familiar commands like git push or git pull to GitHub suddenly became useless. The challenge was: How to transfer code to the server while preserving the commit history, branches, and tags?
Many developers often choose to compress the entire project folder into a .zip file to copy via USB. This method carries significant risks. The .git folder can contain up to 50,000 tiny files. If just one file is corrupted during copying, your entire repository is ruined. Additionally, compressed files are often very heavy because they include node_modules or temporary build files.
A more professional solution is git bundle. It packages the repository into a single binary file, acting like a “portable repo.” You can use this file to git clone or git pull just like a real server.
Why is Git Bundle Better Than Manual Compression?
- Error Control: Git automatically checks integrity during packaging. If the file is corrupted, the extraction command will report it immediately.
- Lightweight: A bundle only contains the necessary commits and objects. A 500MB repo can be reduced to 150MB after bundling.
- Flexible Updates: You can choose to package only the latest commits instead of resending the entire heavy project.
Preparation Before Packaging
The git bundle command is already included in the standard Git installation. You don’t need to install any third-party tools. Before starting, clean up the repo to ensure the bundle file size is optimized.
I usually run the git gc (Garbage Collection) command. This command helps Git reorganize objects and compress data more efficiently.
# Optimize the repo to reduce bundle file size
git gc --prune=now --aggressiveIn practice, this step helps reduce the size by 20-30% for long-term projects with dense commit histories.
Practical Usage
1. Creating a Full Bundle (Full Backup)
To package everything from branches to tags into a single file, use the command:
# Package the entire repo
git bundle create my-project.bundle --allIf you only need to send a specific branch to a colleague to reduce size, use:
# Only package the main branch
git bundle create main-only.bundle main2. Restoring Code from a Bundle File
On the destination computer, treat the bundle file like a GitHub URL. Cloning is very simple:
# Clone the project from the bundled file
git clone my-project.bundle my-new-folderAfter cloning, Git will set the default remote name to origin pointing directly to that bundle file. If you delete or move the bundle file, subsequent fetch commands will not work.
3. Sending Only New Changes (Incremental Update)
This is the most valuable feature. Suppose last week you sent a 1GB bundle file. This week you only coded 10 more commits (about 200KB). Resending 1GB would be a huge waste of time.
Create a “patch” bundle containing commits from the old version to the current one:
# Create a bundle from tag v1.0 to the current state
git bundle create update-v1.1.bundle v1.0..mainThe recipient only needs to download this small file of a few hundred KB and perform a pull:
git pull update-v1.1.bundle mainVerifying File Integrity
Don’t rush to send the file without checking. Since it is a binary format, you cannot use a text editor to view the content inside.
Use the verify command to ensure the file was not corrupted during copying:
git bundle verify my-project.bundleTo see which branches are contained within the bundle, use list-heads:
git bundle list-heads my-project.bundleHard-won Experience
I once managed a team of 8 people working at a client’s office with no internet. Our process was simple: At the end of the day, one person would collect the whole team’s code into a daily_sync.bundle file. This file was copied to a USB and taken home to push to the company’s GitLab. This approach preserved 100% of the commit history without any fear of data loss.
A small note: Bundles do not save the .git/config configuration. When cloning to a new machine, you need to re-configure user.name and user.email to ensure subsequent commits are correctly attributed.
Using git bundle is not just a workaround. It is also an extremely safe backup method for your important projects.
