Git bundle : transférer un dépôt hors-ligne

git bundle crée un fichier autonome contenant tout ou partie d’un dépôt Git, transférable par clé USB, email ou tout autre moyen hors-ligne. C’est la solution pour les environnements air-gapped, les transferts entre réseaux isolés et les sauvegardes portables. Ce guide vous apprend à créer un bundle, vérifier son contenu et cloner ou puller depuis un bundle — avec un exemple complet de workflow hors-ligne.

Prérequis : Remotes fondamentaux et Sélection de révisions.

Ce que vous allez apprendre

Créer un bundle complet d’un dépôt pour transfert hors-ligne
Créer des bundles incrémentaux pour des mises à jour légères
Vérifier l’intégrité d’un bundle avant de l’utiliser
Cloner ou puller depuis un fichier bundle

Quand utiliser `git bundle` ?

Environnement air-gapped : serveurs sans accès internet
Transfert entre réseaux : les deux machines ne se voient pas
Sauvegarde portable : un fichier unique contenant tout l’historique
Bande passante limitée : envoyer un fichier compressé par email
Onboarding : donner le repo complet à un nouveau développeur sur clé USB

Créer un bundle complet

# Bundle contenant TOUT le dépôt (toutes les branches, tous les tags)
git bundle create mon-projet.bundle --all

Le fichier mon-projet.bundle contient l’intégralité du dépôt : tous les commits, branches, tags et objets Git. C’est l’équivalent d’un clone complet dans un fichier unique.

Pour bundler uniquement une branche :

git bundle create main-only.bundle main

Importer un bundle

Cloner depuis un bundle

git clone mon-projet.bundle mon-projet
cd mon-projet

Le bundle est traité comme un remote. Après le clone, configurez le vrai remote :

git remote set-url origin https://github.com/org/mon-projet.git

Ajouter un bundle comme remote

git remote add usb /media/usb/mon-projet.bundle
git fetch usb
git merge usb/main

Vérifier un bundle

Avant d’importer, validez l’intégrité :

git bundle verify mon-projet.bundle

The bundle contains these 3 refs:
a1b2c3d4... refs/heads/main
e4f5a6b7... refs/heads/develop
f0e1d2c3... refs/tags/v1.0.0
The bundle records a complete history.
mon-projet.bundle is okay

Si le bundle est incomplet (incrémental), verify indique quels commits pré-requis manquent.

Bundles incrémentaux

Pour les mises à jour régulières, inutile de re-bundler tout le dépôt. Créez des bundles contenant uniquement les nouveaux commits :

Premier transfert — bundle complet :

git bundle create initial.bundle --all
# Notez le dernier commit inclus
git rev-parse HEAD
# a1b2c3d4...

Transferts suivants — uniquement les nouveautés :

# Depuis le dernier commit transféré
git bundle create update-1.bundle a1b2c3d4..HEAD --all

Sur la machine de destination — appliquer l’incrément :

git bundle verify update-1.bundle   # Vérifier les pré-requis
git fetch /chemin/update-1.bundle main:remotes/usb/main
git merge usb/main

Utiliser des tags comme repères

Les tags simplifient le suivi des incréments :

# Après chaque transfert, tagger le dernier commit envoyé
git tag last-bundle-v1

# Au prochain transfert
git bundle create update.bundle last-bundle-v1..HEAD --all
git tag last-bundle-v2

Workflow air-gapped complet

Machine A (connectée)         Clé USB          Machine B (isolée)
─────────────────────      ────────────      ─────────────────────
git bundle create          copier             git clone bundle
  projet.bundle --all       projet.bundle      projet
                                              git remote set-url
                                                origin ...

[... plus tard ...]

git bundle create          copier             git bundle verify
  update.bundle            update.bundle      git fetch update
  tag-v1..HEAD --all                          git merge
git tag tag-v2

Lister le contenu d’un bundle

git bundle list-heads mon-projet.bundle

a1b2c3d4... refs/heads/main
e4f5a6b7... refs/heads/develop
f0e1d2c3... refs/tags/v1.0.0

Dépannage

Symptôme	Cause probable	Solution
`verify` dit « prerequisite commit missing »	Bundle incrémental, historique manquant	Importez d’abord le bundle complet
Bundle très volumineux	Contient tout l’historique + gros fichiers	Utilisez `--since` ou des plages de commits
`clone` depuis bundle : remote invalide	URL du bundle comme remote	`git remote set-url origin <vraie-url>`
`unbundle` ne fait rien de visible	Les objets sont importés mais pas les branches	Utilisez `fetch` au lieu de `unbundle`

À retenir

git bundle create empaquète tout ou partie d’un dépôt dans un fichier unique
git bundle verify valide l’intégrité avant import
Clone ou fetch depuis un bundle comme depuis un remote
Les bundles incrémentaux (plage de commits) réduisent la taille des transferts
Solution idéale pour les environnements air-gapped et les transferts hors-ligne

Prochaines étapes

Stockage des credentials Gérez vos identifiants Git : cache, store, GCM.

Subtree Intégrez un dépôt sans submodule.

Protocoles Git HTTPS, SSH, Git : comprendre les protocoles de transport.